# AlterActionGenerator - AI Context

## 1. Project Overview

- **Vision:** Generate programmatic Alter Actions for the Alter macOS AI assistant, enabling automated creation of AI-powered workflows that integrate with macOS applications
- **Current Phase:** Initial development and template collection
- **Key Architecture:** YAML-based configuration system for AI workflow definitions with context-aware triggering and templated prompts
- **Development Strategy:** Build a generator tool that understands the Alter Action specification and can create new actions based on user requirements and existing patterns

## 2. Project Structure

**⚠️ CRITICAL: AI agents MUST read the [Project Structure documentation](/docs/ai-context/project-structure.md) before attempting any task to understand the complete technology stack, file tree and project organization.**

AlterActionGenerator follows a YAML-based template collection pattern with documentation and example analysis. The project contains a collection of Alter Action templates in YAML format that define AI-powered workflows for macOS automation. For the complete tech stack and file tree structure, see [docs/ai-context/project-structure.md](/docs/ai-context/project-structure.md).

## 3. Understanding Alter Actions

### What is Alter?

Alter is a macOS AI assistant that lives in the notch and integrates deeply with macOS applications. It provides context-aware AI interactions through "Alter Actions" - YAML-defined workflows that trigger based on system context and execute AI tasks.

### Alter Action YAML Structure

Every Alter Action follows a consistent YAML structure with specific required and optional fields:

#### Required Fields:

```yaml
id: "unique-action-identifier"           # Unique string identifier
name: "Human Readable Action Name"       # Display name in menus
onlyIfRunning: true                      # Only show if specified apps running
onlyIfActive: true                       # Only show if specified apps active
prompt:                                  # AI prompt configuration
  system: |                              # System prompt for AI model
    You are an expert assistant that...
  user: |-                              # User prompt with template variables
    {{ textSelection }}
```

#### Common Optional Fields:

```yaml
description: "What this action does"     # Action explanation
icon: "text.quote"                       # SF Symbols icon name
enabled: true                            # Menu visibility control
core: true                              # Core system action flag
category: "code"                         # Action grouping
color: "purple"                          # Visual theming
consumer: "markdown"                     # Output display format
temperature: 0.7                         # AI model temperature
model: "claude-3-5-sonnet"              # Specific AI model
```

#### Application Context System:

```yaml
installedApplications:                   # Required applications
  - com.microsoft.VSCode
  - com.apple.Terminal
  - dev.zed.Zed
onlyIfRunning: true                      # Only if apps are running
onlyIfActive: true                       # Only if apps are active
onlyIfBrowserTab: ["github", "gitlab"]  # Browser-specific contexts
```

#### Context Keys Available:

Actions can access various macOS context through template variables:

- `{{ textSelection }}` - Selected text in active app
- `{{ selectedFiles }}` - File selections in Finder
- `{{ activeTab }}` - Browser tab information
- `{{ clipboard }}` - System clipboard content
- `{{ mail }}` - Email context data
- `{{ keynote }}` - Keynote presentation data
- `{{ youtubeTranscript }}` - YouTube video transcripts
- `{{ windowContent }}` - Active window content

**Enhanced Context Types (from GUI analysis):**

- `{{ activeApplication }}` - Currently active application
- `{{ activeWindow }}` - Active window information
- `{{ keynoteDocument }}` - Keynote document context
- `{{ currentSlideInKeynote }}` - Current Keynote slide
- `{{ currentThemeInKeynote }}` - Current Keynote theme
- `{{ appleMail }}` - Apple Mail specific context
- `{{ finderFileSelection }}` - Finder file selections
- `{{ activeWindowContent }}` - Content of active window

#### Prompt System with Templating:

```yaml
prompt:
  system: |
    # IDENTITY and PURPOSE
    You are an expert coder that explains code...

    # STEPS
    1. Analyze the provided code
    2. Explain its purpose and functionality

    # OUTPUT INSTRUCTIONS
    - Use clear, concise language
    - Provide structured explanations
  user: |-
    {% if textSelection %}
    Please explain this code:
    {{ textSelection }}
    {% endif %}
    {% if selectedFiles %}
    Files to analyze: {{ selectedFiles }}
    {% endif %}
```

#### Organization and Advanced Features (GUI Analysis):

```yaml
# Organization
folder: "Code Analysis"              # Organize actions in folders
category: "code"                     # Action category

# User Interface
includeProfile: true                 # Include user profile in context
globalKeyboardShortcut: "Cmd+Shift+C"  # Global shortcut
presenter: "markdown"                # Presentation format (markdown/code/diff)

# Advanced Features
model: "claude-sonnet-4-20250514"    # Specific model to use
workspace: "Development"             # Workspace-specific actions
quickAction: "format-output"         # Execute another action after completion
```

#### Parameter System:

Interactive form inputs collected before action execution:

```yaml
parameters:
  - name: language
    label: Target Language
    type: select
    choices: [English, French, Spanish, German]
    default: English
  - name: input
    label: Additional Instructions
    type: text
    placeholder: "Enter your specific requirements..."
  - name: formal
    label: Use Formal Tone
    type: boolean
    default: false
```

**Parameter Types:**

- `boolean` - Toggle switches
- `string` - Single-line text input
- `text` - Multi-line text areas
- `select` - Dropdown menus with choices
- `radio` - Radio button groups
- `float`/`integer` - Numeric inputs
- `search` - Large search input fields

#### Consumer Types (Output Formats):

```yaml
consumer: "markdown"     # Default rich text display
consumer: "inPlace"      # Replace selected text directly
consumer: "code"         # Syntax-highlighted code display
consumer: "diff"         # Show differences/changes
consumer: "magicDiff"    # Enhanced diff viewer
consumer: "keynoteDeckEditor"  # Keynote slide editing
```

#### Advanced Features:

```yaml
needsContextKeys:                        # Required contexts
  - ["textSelection"]                    # Requires text selection
  - ["selectedFiles"]                    # OR file selection

using:                                   # Multi-context support
  - textSelection
  - selectedFiles
  - mail
  - youtubeTranscript

prompt:
  author:                               # Attribution
    name: "fabric"
    link: "https://github.com/danielmiessler/fabric"
```

### Action Categories and Examples:

**Code-Related Actions:**

- `explain-code` - Code explanation and documentation
- `fix-code` - Error detection and correction
- `document-code` - Generate code documentation

**Content Processing:**

- `summarize` - Content summarization with structured output
- `translate` - Multi-language translation
- `rewrite` - Content rewriting and style adjustment

**Git Integration:**

- `git-commit` - Generate commit messages
- `git-review` - Code review assistance

**Creative Actions:**

- `create-react-app` - Generate React applications
- `create-images` - AI image generation
- `create-diagrams` - Diagram creation

### Key Design Principles:

1. **Context-Aware Activation**: Actions appear only when relevant apps/contexts are available
2. **Template-Driven Prompts**: Flexible prompt system with variable substitution
3. **Structured Output**: Consistent formatting with sections and bullet points
4. **User Parameter Integration**: Dynamic form inputs that modify AI behavior
5. **Multi-Modal Support**: Handle text, files, images, and specialized content types
6. **Cross-Application Integration**: Work seamlessly across browsers, editors, and system apps

## 4. Coding Standards & AI Instructions

### General Instructions

- Your most important job is to manage your own context. Always read any relevant files BEFORE planning changes.
- When updating documentation, keep updates concise and on point to prevent bloat.
- Write code following KISS, YAGNI, and DRY principles.
- When in doubt follow proven best practices for implementation.
- Do not commit to git without user approval.
- Do not run any servers, rather tell the user to run servers for testing.
- Always consider industry standard libraries/frameworks first over custom implementations.
- Never mock anything. Never use placeholders. Never omit code.
- Apply SOLID principles where relevant. Use modern framework features rather than reinventing solutions.
- Be brutally honest about whether an idea is good or bad.
- Make side effects explicit and minimal.
- Design database schema to be evolution-friendly (avoid breaking changes).


### File Organization & Modularity

- Default to creating multiple small, focused files rather than large monolithic ones
- Each file should have a single responsibility and clear purpose
- Keep files under 350 lines when possible - split larger files by extracting utilities, constants, types, or logical components into separate modules
- Separate concerns: utilities, constants, types, components, and business logic into different files
- Prefer composition over inheritance - use inheritance only for true 'is-a' relationships, favor composition for 'has-a' or behavior mixing

- Follow existing project structure and conventions - place files in appropriate directories. Create new directories and move files if deemed appropriate.
- Use well defined sub-directories to keep things organized and scalable
- Structure projects with clear folder hierarchies and consistent naming conventions
- Import/export properly - design for reusability and maintainability

### YAML Standards

- **Always** validate YAML structure and required fields
- Use consistent indentation (2 spaces preferred)
- Quote strings containing special characters
- Validate template variable syntax using Stencil format

```yaml
# Good YAML structure
id: "action-name"
name: "Human Readable Name"
description: "Clear action description"
prompt:
  system: |
    # IDENTITY and PURPOSE
    You are an expert assistant...
  user: |-
    {% if textSelection %}
    Selected text: {{ textSelection }}
    {% endif %}
```

### Naming Conventions

- **Action IDs**: kebab-case (e.g., `explain-code`, `git-commit`)
- **Categories**: lowercase single words (e.g., `code`, `git`, `translate`)
- **Parameter names**: camelCase (e.g., `targetLanguage`, `includeComments`)
- **Template variables**: camelCase in mustache syntax (e.g., `{{ textSelection }}`, `{{ selectedFiles }}`)


### Documentation Requirements

- Every Alter Action needs a clear description field
- Complex actions should include usage examples in comments
- Document parameter purposes and expected values
- Include context requirements and application dependencies

```yaml
# Example: Well-documented action
id: "explain-code"
name: "Explain Code"
description: "Provides detailed explanations of selected code, including purpose, functionality, and key concepts"
category: "code"
# Requires: Text selection in code editor
# Usage: Select code in any editor and run action
parameters:
  - name: detailLevel
    label: "Detail Level"
    type: select
    choices: ["basic", "detailed", "comprehensive"]
    default: "detailed"
    # Purpose: Controls depth of explanation
```

### Security & Privacy

- Never include sensitive information in YAML files (API keys, personal data)
- Validate all template variables and user inputs in prompts
- Be cautious with actions that access system files or execute commands
- Review generated prompts for potential injection vulnerabilities
- Ensure context access is limited to what's necessary for the action
- Document privacy implications of context usage (file access, clipboard, etc.)
- Validate YAML structure to prevent malformed configurations

### Error Handling

- Validate YAML syntax and required fields before processing
- Provide clear error messages for malformed actions
- Handle missing context gracefully with fallback behaviors
- Test actions with various context scenarios (missing text selection, no files, etc.)

### Action Design Principles

- Make actions context-aware and only appear when relevant
- Design prompts to be robust against edge cases
- Provide clear user feedback through descriptions and parameter labels
- Test actions across different macOS applications and scenarios
- Keep action scope focused and avoid feature creep
- Design for internationalization when creating user-facing text

### Template Best Practices

- Use conditional blocks to handle optional context (`{% if textSelection %}`)
- Provide fallback prompts when expected context is missing
- Structure system prompts with clear sections (IDENTITY, PURPOSE, STEPS, OUTPUT)
- Make user prompts concise but include necessary context
- Test template rendering with various input combinations


## 5. Multi-Agent Workflows & Context Injection

### Automatic Context Injection for Sub-Agents

When using the Task tool to spawn sub-agents, the core project context (CLAUDE.md, project-structure.md, docs-overview.md) is automatically injected into their prompts via the subagent-context-injector hook. This ensures all sub-agents have immediate access to essential project documentation without the need of manual specification in each Task prompt.


## 6. MCP Server Integrations

### Gemini Consultation Server

**When to use:**

- Complex coding problems requiring deep analysis or multiple approaches
- Code reviews and architecture discussions
- Debugging complex issues across multiple files
- Performance optimization and refactoring guidance
- Detailed explanations of complex implementations
- Highly security relevant tasks

**Automatic Context Injection:**

- The kit's `gemini-context-injector.sh` hook automatically includes two key files for new sessions:
  - `/docs/ai-context/project-structure.md` - Complete project structure and tech stack
  - `/MCP-ASSISTANT-RULES.md` - Your project-specific coding standards and guidelines
- This ensures Gemini always has comprehensive understanding of your technology stack, architecture, and project standards

**Usage patterns:**

```python
# New consultation session (project structure auto-attached by hooks)
mcp__gemini__consult_gemini(
    specific_question="How should I optimize this voice pipeline?",
    problem_description="Need to reduce latency in real-time audio processing",
    code_context="Current pipeline processes audio sequentially...",
    attached_files=[
        "src/core/pipelines/voice_pipeline.py"  # Your specific files
    ],
    preferred_approach="optimize"
)

# Follow-up in existing session
mcp__gemini__consult_gemini(
    specific_question="What about memory usage?",
    session_id="session_123",
    additional_context="Implemented your suggestions, now seeing high memory usage"
)
```

**Key capabilities:**

- Persistent conversation sessions with context retention
- File attachment and caching for multi-file analysis
- Specialized assistance modes (solution, review, debug, optimize, explain)
- Session management for complex, multi-step problems

**Important:** Treat Gemini's responses as advisory feedback. Evaluate the suggestions critically, incorporate valuable insights into your solution, then proceed with your implementation.

### Context7 Documentation Server

**Repository**: [Context7 MCP Server](https://github.com/upstash/context7)

**When to use:**

- Working with external libraries/frameworks (React, FastAPI, Next.js, etc.)
- Need current documentation beyond training cutoff
- Implementing new integrations or features with third-party tools
- Troubleshooting library-specific issues

**Usage patterns:**

```python
# Resolve library name to Context7 ID
mcp__context7__resolve_library_id(libraryName="react")

# Fetch focused documentation
mcp__context7__get_library_docs(
    context7CompatibleLibraryID="/facebook/react",
    topic="hooks",
    tokens=8000
)
```

**Key capabilities:**

- Up-to-date library documentation access
- Topic-focused documentation retrieval
- Support for specific library versions
- Integration with current development practices



## 7. Post-Task Completion Protocol

After completing any coding task, follow this checklist:

### 1. YAML Validation & Quality Checks

After creating or modifying Alter Actions:

- **YAML Syntax**: Validate YAML structure and indentation
- **Required Fields**: Ensure all required fields (id, name, prompt) are present
- **Template Syntax**: Verify Stencil template variables are properly formatted
- **Context Dependencies**: Check that required applications and context are documented

### 2. Action Testing & Verification

- Test actions with various context scenarios (with/without text selection, different apps)
- Verify prompt templates render correctly with sample data
- Ensure action appears in appropriate contexts and is hidden when irrelevant
- Test parameter inputs if the action includes interactive forms