### Initialize AIGI Project (Bash)

Source: https://github.com/ruvnet/ruv-dev/blob/main/aiGI/aigi.md

This command initializes a new AIGI project using the `create-sparc` utility. It sets up the basic project structure and necessary files.

```bash
npx create-sparc aigi init my-project
```

--------------------------------

### Examples of create-sparc init Options

Source: https://github.com/ruvnet/ruv-dev/blob/main/src/cli/commands/help/init.md

Provides examples of using the `create-sparc init` command with various options, such as specifying TypeScript, skipping git initialization, or using a custom template.

```bash
# Create a TypeScript project
npx create-sparc init my-ts-project --typescript

# Initialize SPARC files in current directory without git
npx create-sparc init --no-git

# Create a project with a specific template
npx create-sparc init my-project --template custom-template
```

--------------------------------

### Installing Dependencies - Pseudocode

Source: https://github.com/ruvnet/ruv-dev/blob/main/plans/phases/2-pseudocode.md

This function handles the installation of project dependencies using a package manager determined by the configuration. It gets the appropriate command, executes it in the project directory, and handles potential errors, including retrying network-related failures with exponential backoff. It depends on getPackageManagerCommand, DisplayStatus, executeCommand, isNetworkError, and retryInstallation.

```Pseudocode
FUNCTION installDependencies(config):
    // Determine package manager command
    command = getPackageManagerCommand(config.npmClient)
    
    // Install dependencies
    DisplayStatus("Installing dependencies...")
    
    TRY:
        executeCommand(command + ' install', {
            cwd: config.projectPath,
            stdio: config.verbose ? 'inherit' : 'pipe'
        })
        
        DisplayStatus("Dependencies installed successfully")
    CATCH error:
        IF isNetworkError(error):
            // Retry with exponential backoff for network errors
            retryInstallation(config, 3) // Retry 3 times
        ELSE:
            THROW error
```

--------------------------------

### Example MCP Configuration (mcp.json)

Source: https://github.com/ruvnet/ruv-dev/blob/main/README.md

Provides an example configuration for the `.roo/mcp.json` file, demonstrating how to define an MCP server entry for Supabase. It shows the structure including the command to execute, arguments passed to the server, and a list of actions that are always allowed. Note the use of `${env:VAR_NAME}` for referencing environment variables.

```JSON
{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--access-token",
        "${env:SUPABASE_ACCESS_TOKEN}"
      ],
      "alwaysAllow": [
        "list_tables",
        "execute_sql"
      ]
    }
  }
}
```

--------------------------------

### Get SPARC CLI Help

Source: https://github.com/ruvnet/ruv-dev/blob/main/README.md

Provides commands to access help information for the `create-sparc` CLI. You can get general help for the tool or specific help for individual commands like `init`, `minimal`, and `aigi` to understand their usage and available options.

```bash
npx create-sparc help

# Get help for a specific command
npx create-sparc help init

# Get help for the minimal command
npx create-sparc help minimal

# Get help for the aigi command
npx create-sparc help aigi
```

--------------------------------

### Launch MCP Configuration Wizard (Bash)

Source: https://github.com/ruvnet/ruv-dev/blob/main/README.md

Provides the Bash command to initiate the interactive MCP Configuration Wizard. Running this command starts a guided process in the terminal to discover, configure, and manage MCP server integrations for the project, including setting parameters, credentials, and permissions.

```Bash
npx create-sparc configure-mcp
```

--------------------------------

### Using the Registry Client in JavaScript

Source: https://github.com/ruvnet/ruv-dev/blob/main/src/core/registry-client/README.md

Demonstrates how to initialize the Registry Client and perform common operations like fetching all servers, getting details for a specific server, and searching for servers. It shows basic error handling for these operations.

```javascript
const { RegistryClient } = require('./registry-client');

// Create a new client
const client = new RegistryClient({
  baseUrl: 'https://registry.example.com/api/v1/mcp',
  token: 'your-auth-token'
});

// Get a list of servers
async function getServers() {
  try {
    const response = await client.getServers();
    console.log('Servers:', response.servers);
    console.log('Total:', response.meta.total);
  } catch (error) {
    console.error('Error:', error);
  }
}

// Get details for a specific server
async function getServerDetails(serverId) {
  try {
    const server = await client.getServerDetails(serverId);
    console.log('Server:', server);
  } catch (error) {
    console.error('Error:', error);
  }
}

// Search for servers
async function searchServers(query) {
  try {
    const response = await client.searchServers({
      q: query,
      category: 'database',
      minRating: 4
    });
    console.log('Results:', response.results);
  } catch (error) {
    console.error('Error:', error);
  }
}
```

--------------------------------

### Installation Process Sequence Diagram (Mermaid)

Source: https://github.com/ruvnet/ruv-dev/blob/main/plans/data-flow.md

This sequence diagram illustrates the interaction flow between the user, CLI, and various internal components of the create-sparc package during the project installation and creation process. It shows the sequence of operations from command execution to dependency installation.

```Mermaid
sequenceDiagram
    participant User
    participant CLI
    participant ProjectGenerator
    participant ConfigManager
    participant TemplateEngine
    participant FileManager
    participant SymlinkManager
    participant DependencyInstaller

    User->>CLI: Execute create-sparc command
    CLI->>CLI: Parse arguments and options
    
    CLI->>ProjectGenerator: Initialize project creation
    
    ProjectGenerator->>ConfigManager: Get initial configuration
    ConfigManager-->>ProjectGenerator: Default configuration
    
    alt Interactive mode
        ProjectGenerator->>CLI: Request user inputs
        CLI->>User: Prompt for project details
        User->>CLI: Provide project details
        CLI->>ProjectGenerator: User configuration
    end
    
    ProjectGenerator->>ConfigManager: Validate & merge configuration
    ConfigManager-->>ProjectGenerator: Validated configuration
    
    ProjectGenerator->>FileManager: Create project root directory
    FileManager-->>ProjectGenerator: Directory creation result
    
    ProjectGenerator->>TemplateEngine: Process project templates
    TemplateEngine->>TemplateEngine: Apply template transformations
    TemplateEngine-->>ProjectGenerator: Processed templates
    
    ProjectGenerator->>FileManager: Create project file structure
    FileManager-->>ProjectGenerator: File creation results
    
    ProjectGenerator->>SymlinkManager: Setup symlinks for .roo folder
    
    alt Symlinks supported
        SymlinkManager->>SymlinkManager: Create symbolic links
        SymlinkManager-->>ProjectGenerator: Symlinks created
    else Symlinks not supported
        SymlinkManager->>SymlinkManager: Copy files with metadata
        SymlinkManager-->>ProjectGenerator: Files copied
    end
    
    ProjectGenerator->>ConfigManager: Generate project config files
    ConfigManager-->>ProjectGenerator: Config files created
    
    ProjectGenerator->>DependencyInstaller: Install dependencies
    DependencyInstaller-->>ProjectGenerator: Dependencies installed
    
    ProjectGenerator->>CLI: Project creation complete
    CLI->>User: Display success message and next steps
```

--------------------------------

### Examples with Options for create-sparc minimal

Source: https://github.com/ruvnet/ruv-dev/blob/main/src/cli/commands/help/minimal.md

Demonstrates how to use the `create-sparc minimal` command with various options like `--typescript`, `--no-git`, and `--force`.

```bash
npx create-sparc minimal init my-ts-project --typescript
npx create-sparc minimal init --no-git
npx create-sparc minimal init my-project --force
```

--------------------------------

### Project Configuration Object - JavaScript

Source: https://github.com/ruvnet/ruv-dev/blob/main/plans/data-flow.md

Represents the central configuration structure used throughout the project setup process. It defines project name, path, template, feature flags, npm client, and git options.

```javascript
{
  projectName: "my-sparc-project",
  projectPath: "/path/to/my-sparc-project",
  template: "default",
  installDependencies: true,
  symlink: {
    enabled: true,
    paths: [".roo", ".roomodes"]
  },
  features: {
    typescript: true,
    testing: true,
    cicd: false
  },
  npmClient: "npm", // or "yarn", "pnpm"
  git: {
    init: true,
    initialCommit: true
  }
}
```

--------------------------------

### Running create-sparc via npx (Bash)

Source: https://github.com/ruvnet/ruv-dev/blob/main/README.md

Explains how to execute the `create-sparc` tool directly using npx without a global installation. This is the recommended way to use the tool for initialization.

```bash
npx create-sparc init
```

--------------------------------

### Using the Clinerules Management Script (Bash)

Source: https://github.com/ruvnet/ruv-dev/blob/main/clinerules-bank/docs/folder-system-guide.md

Provides examples of common commands for the manage-rules.sh utility script. This script is used to list, activate, deactivate, backup, restore, and clear Clinerules files within the project's .clinerules and clinerules-bank directories. It requires the manage-rules.sh script to be present in the clinerules-bank directory.

```Bash
# List all available rule files
./clinerules-bank/manage-rules.sh list

# List currently active rules
./clinerules-bank/manage-rules.sh active

# Activate a specific rule file
./clinerules-bank/manage-rules.sh activate frameworks/react.md

# Deactivate a specific rule file
./clinerules-bank/manage-rules.sh deactivate frameworks/react.md

# Backup current active rules
./clinerules-bank/manage-rules.sh backup

# Restore rules from backup
./clinerules-bank/manage-rules.sh restore

# Remove all active rules
./clinerules-bank/manage-rules.sh clear
```

--------------------------------

### Example: Safely Updating Configuration File (JavaScript)

Source: https://github.com/ruvnet/ruv-dev/blob/main/src/core/file-manager/README.md

This example function demonstrates a common use case: safely updating a configuration file. It reads the current configuration, merges it with new updates using a specified strategy, and then writes the merged configuration back to the file, automatically creating a backup.

```javascript
// Example: Safely update a configuration file
async function updateConfiguration(configPath, updates) {
  try {
    // Read the current configuration
    const currentConfig = await fileManager.safeReadConfig(configPath);
    
    // Merge with updates
    const newConfig = fileManager.mergeConfigurations(currentConfig, updates, {
      strategy: 'deep'
    });
    
    // Write the updated configuration with backup
    await fileManager.safeWriteConfig(configPath, newConfig);
    
    return { success: true, config: newConfig };
  } catch (error) {
    console.error(`Failed to update configuration: ${error.message}`);
    return { success: false, error };
  }
}
```

--------------------------------

### Project Initialization Flow - create-sparc NPX - Pseudocode

Source: https://github.com/ruvnet/ruv-dev/blob/main/plans/phases/2-pseudocode.md

Describes the process for initializing a new project. It validates the project name, prepares configuration (potentially interactively), validates the final configuration, creates the project directory and structure from templates, sets up symlinks (with fallback), generates config files, installs dependencies, and initializes Git. Includes error handling.

```Pseudocode
FUNCTION initProject(projectName, options):
    // Validation
    IF NOT isValidProjectName(projectName):
        Display validation error
        EXIT with error
    
    // Configuration preparation
    config = createConfigurationObject(projectName, options)
    
    // Interactive mode
    IF options.interactive:
        config = promptForConfiguration(config)
    
    // Validate configuration
    validationResult = validateConfiguration(config)
    IF NOT validationResult.valid:
        Display validation errors
        EXIT with error
    
    // Project creation
    TRY:
        // Start project creation
        Display "Creating project..."
        
        // Create project directory
        createProjectDirectory(config.projectPath)
        
        // Process templates
        templateResult = processTemplates(config)
        
        // Create project structure
        createProjectStructure(templateResult, config)
        
        // Setup symlinks
        IF config.symlink.enabled:
            TRY:
                setupSymlinks(config)
            CATCH symlinkError:
                logWarning("Symlink creation failed, falling back to copy")
                fallbackToCopy(config, symlinkError)
        
        // Generate configuration files
        generateConfigFiles(config)
        
        // Install dependencies
        IF config.installDependencies:
            installDependencies(config)
        
        // Git initialization
        IF config.git.init:
            initializeGit(config)
        
        // Display success message
        DisplaySuccess("Project created successfully at " + config.projectPath)
        DisplayNextSteps(config)
        
    CATCH error:
        HandleError(error)
        EXIT with error
        
    EXIT with success
```

--------------------------------

### Configuration Object Structure - Pseudocode

Source: https://github.com/ruvnet/ruv-dev/blob/main/plans/phases/2-pseudocode.md

This defines the structure of the primary configuration object used to control project generation and setup. It includes properties for project details, template path, dependency installation, symlink settings, feature flags, npm client choice, git options, and verbosity. It outlines the expected types and nested structures.

```Pseudocode
ConfigurationObject {
    projectName: string,
    projectPath: string,
    template: string,
    installDependencies: boolean,
    symlink: {
        enabled: boolean,
        paths: string[]
    },
    features: {
        typescript: boolean,
        testing: boolean,
        cicd: boolean,
        [key: string]: boolean
    },
    npmClient: "npm" | "yarn" | "pnpm",
    git: {
        init: boolean,
        initialCommit: boolean
    },
    verbose: boolean
}
```

--------------------------------

### Initialize AIGI Project Without Git

Source: https://github.com/ruvnet/ruv-dev/blob/main/src/cli/commands/help/aigi.md

Illustrates the use of the --no-git option when initializing an AIGI project via npx. This command initializes the project files but skips the default Git repository setup.

```bash
npx create-sparc aigi init --no-git
```

--------------------------------

### Run Interactive MCP Wizard

Source: https://github.com/ruvnet/ruv-dev/blob/main/src/cli/commands/help/wizard.md

Execute the create-sparc wizard command without any options to start the interactive configuration process for MCP servers.

```bash
create-sparc wizard
```

--------------------------------

### Create TypeScript AIGI Project

Source: https://github.com/ruvnet/ruv-dev/blob/main/src/cli/commands/help/aigi.md

Provides an example of using the --typescript option with npx create-sparc aigi init. This command creates a new AIGI project pre-configured for TypeScript development.

```bash
npx create-sparc aigi init my-ts-aigi-project --typescript
```

--------------------------------

### Starting Mastra Agent Locally (CLI)

Source: https://github.com/ruvnet/ruv-dev/blob/main/aiGI/plans/research.md

Use this command to launch the Mastra agent service on your local machine for development or testing purposes.

```Shell
npx mastra-agent start
```

--------------------------------

### Supabase MCP Server Definition Response (HTTP/JSON)

Source: https://github.com/ruvnet/ruv-dev/blob/main/plans/mcp-registry-api-spec.md

Example HTTP response body containing the detailed configuration and metadata for the Supabase MCP server, including arguments, permissions, examples, and Roomode template.

```HTTP
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "supabase",
  "name": "Supabase",
  "description": "Supabase MCP server for database operations",
  "version": "1.0.0",
  "command": "npx",
  "args": [
    "-y",
    "@supabase/mcp-server-supabase@latest"
  ],
  "requiredArgs": [
    {
      "name": "access-token",
      "description": "Supabase access token",
      "secret": true,
      "envVar": "SUPABASE_ACCESS_TOKEN"
    },
    {
      "name": "project-id",
      "description": "Supabase project ID",
      "secret": false
    }
  ],
  "optionalArgs": [
    {
      "name": "region",
      "description": "Supabase region",
      "default": "us-east-1"
    }
  ],
  "recommendedPermissions": [
    "list_tables",
    "execute_sql",
    "list_projects"
  ],
  "documentation": "https://example.com/docs/supabase-mcp",
  "tags": ["database", "backend"],
  "popularity": 4.8,
  "examples": [
    {
      "name": "Basic configuration",
      "config": {
        "command": "npx",
        "args": [
          "-y",
          "@supabase/mcp-server-supabase@latest",
          "--access-token",
          "${env:SUPABASE_ACCESS_TOKEN}",
          "--project-id",
          "abcdef123456"
        ],
        "alwaysAllow": [
          "list_tables",
          "execute_sql"
        ]
      }
    },
    {
      "name": "Advanced configuration",
      "config": {
        "command": "npx",
        "args": [
          "-y",
          "@supabase/mcp-server-supabase@latest",
          "--access-token",
          "${env:SUPABASE_ACCESS_TOKEN}",
          "--project-id",
          "abcdef123456",
          "--region",
          "eu-west-1"
        ],
        "alwaysAllow": [
          "list_tables",
          "execute_sql",
          "list_projects",
          "create_table"
        ]
      }
    }
  ],
  "roomodeTemplate": {
    "slug": "mcp-supabase",
    "name": "Supabase Database Assistant",
    "roleDefinition": "You are a Supabase database specialist who helps users interact with their Supabase database through the MCP integration. You can execute SQL queries, list tables, and help users understand their database schema.",
    "customInstructions": "When users ask about their database, use the MCP tools to list tables and explore the schema. For data operations, help users craft SQL queries and execute them safely.",
    "groups": [
      "read",
      "edit",
      "mcp"
    ]
  }
}
```

--------------------------------

### Initialize SPARC Files in Existing Project

Source: https://github.com/ruvnet/ruv-dev/blob/main/README.md

Shows how to add necessary SPARC files (`.roo` and `.roomodes`) to an existing project without creating a new project structure. This is useful for integrating SPARC methodology into pre-existing codebases. Examples are provided for both `npx` and direct `node` execution.

```bash
# Navigate to your project directory
cd my-existing-project

# Initialize SPARC files (.roo and .roomodes) without creating project structure
npx create-sparc init

# Or if running with Node directly
node path/to/bin/index.js init
```

--------------------------------

### Activating SPARC Role-Based Rule Files (Bash)

Source: https://github.com/ruvnet/ruv-dev/blob/main/clinerules-bank/docs/folder-system-guide.md

Demonstrates how to activate specific rule files associated with different SPARC development roles using the `manage-rules.sh` script. This command switches the active rule set to match the current role's responsibilities.

```bash
# When working as an architect
./clinerules-bank/manage-rules.sh activate orchestration/architect-role.md

# When implementing components
./clinerules-bank/manage-rules.sh activate orchestration/auto-coder-role.md
```

--------------------------------

### Enable Debug Output for MCP Wizard

Source: https://github.com/ruvnet/ruv-dev/blob/main/src/cli/commands/help/wizard.md

Run any wizard command with the --debug flag to get verbose output, which is helpful for troubleshooting issues.

```bash
create-sparc wizard --list --debug
```

--------------------------------

### Secure Credential Usage Example (JSON)

Source: https://github.com/ruvnet/ruv-dev/blob/main/src/core/mcp-wizard/SECURITY.md

Demonstrates how to use environment variable references (${env:VAR_NAME}) instead of hardcoded sensitive values within an MCP configuration file, specifically for an access token.

```json
{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase@1.0.0",
        "--access-token",
        "${env:SUPABASE_ACCESS_TOKEN}"
      ],
      "alwaysAllow": ["list_tables", "execute_query"]
    }
  }
}
```

--------------------------------

### Template Context Object - JavaScript

Source: https://github.com/ruvnet/ruv-dev/blob/main/plans/data-flow.md

Provides context data used specifically during the template processing phase. It includes project details, enabled features, author information, and relevant file paths.

```javascript
{
  project: {
    name: "my-sparc-project",
    safeName: "my_sparc_project", // Safe for variable names
    description: "My SPARC project description"
  },
  features: {
    typescript: true,
    testing: true,
    cicd: false
  },
  author: {
    name: "Developer Name",
    email: "dev@example.com"
  },
  paths: {
    root: "/path/to/my-sparc-project",
    roo: "/path/to/my-sparc-project/.roo",
    roomodes: "/path/to/my-sparc-project/.roomodes"
  }
}
```

--------------------------------

### Configuring CLI Entry Point in package.json

Source: https://github.com/ruvnet/ruv-dev/blob/main/aiGI/plans/research.md

This snippet shows how to configure the 'bin' field in the package.json file. It maps the desired command name ('mastra-agent') to the compiled JavaScript file ('dist/cli.js') that serves as the CLI entry point, allowing users to run the command via npx or globally if installed.

```JSON
"bin": {"mastra-agent": "dist/cli.js"}
```

--------------------------------

### MCP Wizard CLI Commands - Bash

Source: https://github.com/ruvnet/ruv-dev/blob/main/README.md

Provides a list of command-line options for interacting with the MCP Wizard, including starting the interactive mode, listing, discovering, adding, updating, removing, validating, backing up, and auditing configurations.

```bash
# Start the interactive wizard
npx create-sparc configure-mcp

# List configured MCP servers
npx create-sparc configure-mcp --list

# Discover available MCP servers
npx create-sparc configure-mcp --discover

# Add a specific MCP server
npx create-sparc configure-mcp --add <server-id>

# Update a configured MCP server
npx create-sparc configure-mcp --update <server-id>

# Remove a configured MCP server
npx create-sparc configure-mcp --remove <server-id>

# Validate current MCP configuration
npx create-sparc configure-mcp --validate

# Create a backup of current configuration
npx create-sparc configure-mcp --backup

# Perform security audit on MCP configuration
npx create-sparc configure-mcp --security-audit

# Automatically fix security issues
npx create-sparc configure-mcp --security-audit --auto-fix

# Validate environment variable references
npx create-sparc configure-mcp --validate-env
```

--------------------------------

### MCP Security Module CLI Usage (Bash)

Source: https://github.com/ruvnet/ruv-dev/blob/main/src/core/mcp-wizard/SECURITY.md

Provides examples of using the MCP Security Module via the command line interface, including performing a security audit, automatically fixing issues, and validating environment variable references.

```bash
# Perform a security audit
npx create-sparc configure-mcp --security-audit

# Automatically fix security issues
npx create-sparc configure-mcp --security-audit --auto-fix

# Validate environment variable references
npx create-sparc configure-mcp --validate-env
```

--------------------------------

### Using Mock Registry in Jest Tests - JavaScript

Source: https://github.com/ruvnet/ruv-dev/blob/main/src/core/registry-client/README-mock.md

Provides an example of integrating the mock registry client into a Jest test suite. It demonstrates using `beforeAll`, `afterAll`, and `beforeEach` hooks to set up, restore, and reset the mock registry, and how to use helper functions like `getSampleServerMetadata`.

```javascript
const { setupMockRegistry, getSampleServerMetadata } = require('../utils/mock-registry');

describe('My Test Suite', () => {
  let mockRegistry;

  beforeAll(() => {
    // Setup mock registry
    mockRegistry = setupMockRegistry();
  });

  afterAll(() => {
    // Restore original registry client
    mockRegistry.restore();
  });

  beforeEach(() => {
    // Reset mock registry between tests
    mockRegistry.reset();
  });

  test('my test', async () => {
    // Get sample server metadata
    const serverMetadata = await getSampleServerMetadata('supabase');
    
    // Use the metadata in your test
    // ...
  });
});
```

--------------------------------

### Create Configuration Object - create-sparc NPX - Pseudocode

Source: https://github.com/ruvnet/ruv-dev/blob/main/plans/phases/2-pseudocode.md

A key function for managing configuration. It creates a base configuration object for a new project using the provided project name and command-line options, applying default values where options are not specified. It includes settings for project path, template, dependency installation, symlinks, features (TypeScript, testing, CI/CD), npm client, and Git initialization.

```Pseudocode
FUNCTION createConfigurationObject(projectName, options):
    // Create base configuration object with defaults
    config = {
        projectName: projectName,
        projectPath: resolvePath(projectName),
        template: options.template || "default",
        installDependencies: !options.skipInstall,
        symlink: {
            enabled: options.symlink !== false,
            paths: [".roo", ".roomodes"]
        },
        features: {
            typescript: options.typescript || false,
            testing: options.testing || true,
            cicd: options.cicd || false
        },
        npmClient: determineNpmClient(options),
        git: {
            init: options.git !== false,
            initialCommit: options.git !== false
        },
        verbose: options.verbose || false
    }
    
    RETURN config
```

--------------------------------

### Running Agent CLI via npx

Source: https://github.com/ruvnet/ruv-dev/blob/main/aiGI/plans/research.md

This command demonstrates the standard way to execute the agent's command-line interface using npx. This works after the package is installed locally or globally, or if using npm link during development.

```Shell
npx mastra-agent
```

--------------------------------

### Defining Configuration Schema - JSON

Source: https://github.com/ruvnet/ruv-dev/blob/main/plans/phases/3-architecture.md

This JSON schema defines the structure and validation rules for the create-sparc configuration file. It specifies properties like project name, path, template, dependency installation options, symlink settings, feature flags (TypeScript, testing, CI/CD), preferred npm client, and git initialization options.

```json
{
  "type": "object",
  "properties": {
    "projectName": {
      "type": "string",
      "description": "Name of the project",
      "pattern": "^[a-zA-Z0-9-_]+$"
    },
    "projectPath": {
      "type": "string",
      "description": "Path to the project directory"
    },
    "template": {
      "type": "string",
      "description": "Template to use for project generation",
      "default": "default"
    },
    "installDependencies": {
      "type": "boolean",
      "description": "Whether to install dependencies",
      "default": true
    },
    "symlink": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Whether to use symlinks",
          "default": true
        },
        "paths": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": [".roo", ".roomodes"]
        }
      }
    },
    "features": {
      "type": "object",
      "properties": {
        "typescript": {
          "type": "boolean",
          "default": false
        },
        "testing": {
          "type": "boolean",
          "default": true
        },
        "cicd": {
          "type": "boolean",
          "default": false
        }
      }
    },
    "npmClient": {
      "type": "string",
      "enum": ["npm", "yarn", "pnpm"],
      "default": "npm"
    },
    "git": {
      "type": "object",
      "properties": {
        "init": {
          "type": "boolean",
          "default": true
        },
        "initialCommit": {
          "type": "boolean",
          "default": true
        }
      }
    }
  },
  "required": ["projectName", "projectPath"]
}
```

--------------------------------

### Get Server Categories Response (HTTP/JSON)

Source: https://github.com/ruvnet/ruv-dev/blob/main/plans/mcp-registry-api-spec.md

Example HTTP response body returning a JSON array of server categories, including their name, count, and description.

```HTTP
HTTP/1.1 200 OK
Content-Type: application/json

{
  "categories": [
    {
      "name": "database",
      "count": 3,
      "description": "Database and storage services"
    },
    {
      "name": "ai",
      "count": 5,
      "description": "Artificial intelligence and machine learning services"
    },
    {
      "name": "backend",
      "count": 8,
      "description": "Backend and server-side services"
    },
    {
      "name": "frontend",
      "count": 2,
      "description": "Frontend and client-side services"
    },
    {
      "name": "devops",
      "count": 4,
      "description": "DevOps and infrastructure services"
    }
  ]
}
```

--------------------------------

### Using npx to Initialize SPARC Project

Source: https://github.com/ruvnet/ruv-dev/blob/main/src/cli/commands/help/init.md

Demonstrates how to use the `create-sparc init` command via `npx` to either create a new project in a specified directory or initialize SPARC files in the current directory.

```bash
# Create a new project with a specific name
npx create-sparc init my-project

# Initialize SPARC files in the current directory
npx create-sparc init
```

--------------------------------

### Example Generated Supabase Roomode (JSON)

Source: https://github.com/ruvnet/ruv-dev/blob/main/plans/mcp-roomode-templates.md

This JSON object represents a sample generated roomode configuration for a Supabase database integration. It defines the slug, name, AI model, role definition, custom instructions, required permission groups (including 'database'), and source for the roomode.

```json
{
  "slug": "mcp-supabase",
  "name": "Supabase Database Assistant",
  "model": "claude-3-7-sonnet-20250219",
  "roleDefinition": "You are a specialized database assistant for working with Supabase. You help users interact with their database by writing and executing SQL queries, exploring database schema, and managing database objects.\n\nYour capabilities include:\n- Listing available tables and views\n- Describing table schemas\n- Writing and executing SQL queries\n- Analyzing query results\n- Suggesting database optimizations\n- Creating and modifying database objects\n\nYou have access to MCP tools that allow you to directly interact with the Supabase database. Use these tools responsibly and always confirm potentially destructive operations with the user.",
  "customInstructions": "When working with Supabase database:\n\n1. Always list available tables first when exploring a new database.\n2. Use SELECT queries before suggesting modifications to data.\n3. Explain the purpose and impact of SQL queries before executing them.\n4. For destructive operations (DELETE, DROP, etc.), always ask for confirmation.\n5. Format query results in a readable way using markdown tables.\n6. Suggest indexes or optimizations when appropriate.\n7. When errors occur, explain them in simple terms and suggest fixes.\n\nUse these MCP tools:\n- `list_tables` to show available tables\n- `describe_table` to show table schema\n- `execute_sql` to run SQL queries\n- `explain_query` to analyze query performance",
  "groups": [
    "read",
    "edit",
    "mcp",
    "database"
  ],
  "source": "project"
}
```

--------------------------------

### Component Addition Flow - create-sparc NPX - Pseudocode

Source: https://github.com/ruvnet/ruv-dev/blob/main/plans/phases/2-pseudocode.md

Details the process for adding a new component to an existing project. It validates the component name, locates the project configuration, creates component-specific configuration, processes the component template, adds the component files, updates the project configuration, and optionally installs component dependencies. Includes error handling.

```Pseudocode
FUNCTION addComponent(componentName, options):
    // Validation
    IF NOT isValidComponentName(componentName):
        Display validation error
        EXIT with error
    
    // Locate existing project
    projectConfig = findProjectConfiguration()
    IF NOT projectConfig:
        Display error "Not a SPARC project directory"
        EXIT with error
    
    // Component configuration
    componentConfig = createComponentConfig(componentName, options, projectConfig)
    
    // Process component template
    templateResult = processComponentTemplate(componentConfig)
    
    // Add component to project
    TRY:
        addComponentFiles(templateResult, componentConfig)
        updateProjectConfiguration(componentConfig)
        
        IF componentConfig.installDependencies:
            installComponentDependencies(componentConfig)
        
        DisplaySuccess("Component added successfully")
        
    CATCH error:
        HandleError(error)
        EXIT with error
        
    EXIT with success
```

--------------------------------

### List All MCP Servers Response (200 OK)

Source: https://github.com/ruvnet/ruv-dev/blob/main/plans/mcp-registry-api-spec.md

This snippet provides an example HTTP 200 OK response body for the GET /servers endpoint, showing the structure of the server list and pagination metadata.

```HTTP
HTTP/1.1 200 OK
Content-Type: application/json

{
  "servers": [
    {
      "id": "supabase",
      "name": "Supabase",
      "description": "Supabase MCP server for database operations",
      "version": "1.0.0",
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase@latest"
      ],
      "requiredArgs": [
        {
          "name": "access-token",
          "description": "Supabase access token",
          "secret": true,
          "envVar": "SUPABASE_ACCESS_TOKEN"
        },
        {
          "name": "project-id",
          "description": "Supabase project ID",
          "secret": false
        }
      ],
      "optionalArgs": [
        {
          "name": "region",
          "description": "Supabase region",
          "default": "us-east-1"
        }
      ],
      "recommendedPermissions": [
        "list_tables",
        "execute_sql",
        "list_projects"
      ],
      "documentation": "https://example.com/docs/supabase-mcp",
      "tags": ["database", "backend"],
      "popularity": 4.8
    },
    {
      "id": "openai",
      "name": "OpenAI",
      "description": "OpenAI MCP server for AI operations",
      "version": "1.0.0",
      "command": "npx",
      "args": [
        "-y",
        "@openai/mcp-server@latest"
      ],
      "requiredArgs": [
        {
          "name": "api-key",
          "description": "OpenAI API key",
          "secret": true,
          "envVar": "OPENAI_API_KEY"
        }
      ],
      "optionalArgs": [
        {
          "name": "organization",
          "description": "OpenAI organization ID",
          "secret": false
        },
        {
          "name": "model",
          "description": "Default model to use",
          "default": "gpt-4"
        }
      ],
      "recommendedPermissions": [
        "create_completion",
        "list_models",
        "create_embedding"
      ],
      "documentation": "https://example.com/docs/openai-mcp",
      "tags": ["ai", "nlp"],
      "popularity": 4.9
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "pageSize": 10,
    "lastUpdated": "2025-04-20T12:00:00Z"
  }
}
```

--------------------------------

### Initializing Mock Registry Client - JavaScript

Source: https://github.com/ruvnet/ruv-dev/blob/main/src/core/registry-client/README-mock.md

Demonstrates the basic usage of the MockRegistryClient. It shows how to create an instance of the client and use it to call a method like `getServers`, handling potential errors.

```javascript
const { MockRegistryClient } = require('../../src/core/registry-client');

// Create a mock registry client
const client = new MockRegistryClient();

// Use it like the real client
async function getServers() {
  try {
    const response = await client.getServers();
    console.log('Servers:', response.servers);
  } catch (error) {
    console.error('Error:', error);
  }
}
```

--------------------------------

### Creating a Standard SPARC Project (Bash)

Source: https://github.com/ruvnet/ruv-dev/blob/main/README.md

Demonstrates how to initialize a new standard SPARC project. You can specify a directory name to create a new folder or run it in the current directory to initialize there. A shorthand syntax is also available.

```bash
# Create a full project with a specific name
npx create-sparc init my-project

# Create only .roo and .roomodes files in the current directory
npx create-sparc init
```

```bash
npx create-sparc my-project
```

--------------------------------

### Initialize AIGI Project with npx

Source: https://github.com/ruvnet/ruv-dev/blob/main/src/cli/commands/help/aigi.md

Demonstrates the basic usage of the create-sparc aigi command via npx. It shows how to create a new project with a specified name or initialize AIGI files in the current directory.

```bash
npx create-sparc aigi init my-aigi-project

npx create-sparc aigi init
```

--------------------------------

### Main Program Flow - create-sparc NPX - Pseudocode

Source: https://github.com/ruvnet/ruv-dev/blob/main/plans/phases/2-pseudocode.md

Outlines the main entry point of the create-sparc NPX package. It parses command-line arguments, identifies the requested command (init, add, help, version), and dispatches to the appropriate function or displays help/version information. Handles unknown commands by displaying an error.

```Pseudocode
FUNCTION main():
    Parse command line arguments and options
    Identify command (init, add, help, etc.)
    Validate global options
    
    IF command is "help" or "--help" flag is set:
        Display help information based on context
        EXIT with success
    
    IF command is "version" or "--version" flag is set:
        Display version information
        EXIT with success
    
    IF command is "init":
        Execute initProject() with parsed options
    ELSE IF command is "add":
        Execute addComponent() with parsed options
    ELSE:
        Display error for unknown command
        EXIT with error
        
    EXIT with success
```

--------------------------------

### Get Server Categories Request (HTTP)

Source: https://github.com/ruvnet/ruv-dev/blob/main/plans/mcp-registry-api-spec.md

HTTP GET request to retrieve a list of available server categories from the registry API. Requires authentication.

```HTTP
GET /categories
Host: registry.example.com
Authorization: Bearer <token>
```

--------------------------------

### Initializing SPARC Project with create-sparc (Bash)

Source: https://github.com/ruvnet/ruv-dev/blob/main/README.md

Steps to create a new directory, navigate into it, and initialize a SPARC project using the `npx create-sparc init` command. This sets up the basic structure for a SPARC-based project.

```bash
mkdir my-sparc-project
cd my-sparc-project
npx create-sparc init
```

--------------------------------

### Get MCP Server Details Request

Source: https://github.com/ruvnet/ruv-dev/blob/main/plans/mcp-registry-api-spec.md

This snippet shows the HTTP GET request to retrieve detailed information for a specific MCP server using its unique ID in the path.

```HTTP
GET /servers/{server-id}
Host: registry.example.com
Authorization: Bearer <token>
```

--------------------------------

### Using Node Directly to Initialize SPARC Project

Source: https://github.com/ruvnet/ruv-dev/blob/main/src/cli/commands/help/init.md

Shows how to run the `create-sparc init` command directly using Node.js, either creating a new project or initializing the current directory. Note the absence of 'create-sparc' in the command when running directly.

```bash
# Create a new project with a specific name
node bin/index.js init my-project

# Initialize SPARC files in the current directory
node bin/index.js init
```

--------------------------------

### Initializing AIGI Framework Project

Source: https://github.com/ruvnet/ruv-dev/blob/main/README.md

This snippet provides bash commands to initialize a new project using the AIGI framework. The first command creates a new project with a specified name, while the second command initializes the necessary AIGI files in the current directory.

```bash
# Create a new AIGI framework with a specific name
npx create-sparc aigi init my-project

# Initialize AIGI files in the current directory
npx create-sparc aigi init
```

--------------------------------

### Check Environment Variable (Bash)

Source: https://github.com/ruvnet/ruv-dev/blob/main/src/cli/commands/help/wizard.md

Example command to verify if an environment variable is set and display its value in a Bash shell.

```bash
echo $OPENAI_API_KEY
```

--------------------------------

### Release Workflow Diagram (Mermaid)

Source: https://github.com/ruvnet/ruv-dev/blob/main/plans/phases/5-completion.md

This diagram illustrates the project's release workflow, detailing the steps from developer commit through CI/CD, QA verification, publishing to npm, and availability to end users, including feedback loops.

```mermaid
sequenceDiagram
    participant Dev as Developer
    participant CI as CI/CD Pipeline
    participant QA as Quality Assurance
    participant Reg as Registry (npm)
    participant Users as End Users
    
    Dev->>CI: Commit changes
    CI->>CI: Run tests and checks
    CI->>QA: Deploy to staging
    
    QA->>QA: Perform verification
    alt Failed Verification
        QA->>Dev: Return for fixes
        Dev->>CI: Submit fixes
    else Passed Verification
        QA->>CI: Approve release
    end
    
    CI->>CI: Build release package
    CI->>CI: Generate release notes
    CI->>Reg: Publish to npm
    
    Reg->>Users: Make available to users
    Users->>QA: Provide feedback
    QA->>Dev: Forward feedback
```

--------------------------------

### Authentication Header Example

Source: https://github.com/ruvnet/ruv-dev/blob/main/plans/mcp-registry-api-spec.md

This snippet demonstrates the required Authorization header format using a Bearer token for authenticating API requests.

```HTTP
Authorization: Bearer <token>
```

--------------------------------

### Initializing AIGI Project with create-sparc (Bash)

Source: https://github.com/ruvnet/ruv-dev/blob/main/README.md

Steps to create a new directory, navigate into it, and initialize an AIGI project using the `npx create-sparc aigi init` command. This sets up the basic structure for an AI-driven code generation project.

```bash
mkdir my-aigi-project
cd my-aigi-project
npx create-sparc aigi init
```

--------------------------------

### Running Tests with npm

Source: https://github.com/ruvnet/ruv-dev/blob/main/__tests__/README.md

Provides various npm commands to execute the test suite. Includes options for running all tests, specific test types (unit, integration), watch mode for development, and generating a coverage report.

```bash
# Run all tests
npm test

# Run only unit tests
npm run test:unit

# Run only integration tests
npm run test:integration

# Run tests in watch mode (useful during development)
npm run test:watch

# Run tests with coverage report
npm run test:coverage
```

--------------------------------

### Configure MCP Servers using create-sparc JavaScript

Source: https://github.com/ruvnet/ruv-dev/blob/main/src/core/mcp-wizard/README.md

Demonstrates how to use the `mcpWizard.configureServers` function to configure one or more MCP servers. It requires server metadata and user-provided parameters, and allows specifying project paths and merge options.

```javascript
const { mcpWizard } = require('create-sparc');

// Server metadata from registry
const serverMetadata = {
  id: 'supabase',
  name: 'Supabase',
  description: 'Supabase MCP server for database operations',
  version: '1.0.0',
  command: 'npx',
  args: ['-y', '@supabase/mcp-server-supabase@latest'],
  requiredArgs: [
    {
      name: 'access-token',
      description: 'Supabase access token',
      secret: true,
      envVar: 'SUPABASE_ACCESS_TOKEN'
    }
  ],
  recommendedPermissions: ['list_tables', 'execute_sql'],
  tags: ['database']
};

// User-provided parameters
const serverParams = {
  'access-token': 'your-token',
  'project-id': 'your-project'
};

// Configure the server
const result = await mcpWizard.configureServers([
  { metadata: serverMetadata, params: serverParams }
], {
  projectPath: process.cwd(),
  mcpConfigPath: '.roo/mcp.json',
  roomodesPath: '.roomodes',
  mergeExisting: true
});

if (result.success) {
  console.log('MCP server configured successfully!');
} else {
  console.error('Failed to configure MCP server:', result.error);
}
```

--------------------------------

### HTTP 404 Not Found Error Response

Source: https://github.com/ruvnet/ruv-dev/blob/main/plans/mcp-registry-api-spec.md

Example HTTP response for a resource not found error, indicating the requested resource does not exist on the server.

```http
HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": "not_found",
  "message": "The requested resource was not found",
  "code": "RES_001"
}
```

--------------------------------

### Setting Up Symlinks - Pseudocode

Source: https://github.com/ruvnet/ruv-dev/blob/main/plans/phases/2-pseudocode.md

This function attempts to create symbolic links based on paths defined in the configuration. It first checks if symlinks are supported on the current platform. For each path, it resolves source and target paths, creates necessary parent directories, creates the symlink, and tracks it. It depends on isSymlinkSupported, resolveTemplatePath, resolvePath, createParentDirectories, createSymlink, and trackSymlink.

```Pseudocode
FUNCTION setupSymlinks(config):
    // Check symlink support
    IF NOT isSymlinkSupported():
        THROW new Error("Symlinks not supported on this platform")
    
    // Create symlinks for defined paths
    FOR EACH path IN config.symlink.paths:
        sourcePath = resolveTemplatePath(path, config.template)
        targetPath = resolvePath(config.projectPath, path)
        
        createParentDirectories(targetPath)
        createSymlink(sourcePath, targetPath)
        
        // Track symlink for reporting
        trackSymlink(sourcePath, targetPath)
```

--------------------------------

### Initialize AIGI Project with Node Directly

Source: https://github.com/ruvnet/ruv-dev/blob/main/src/cli/commands/help/aigi.md

Shows how to run the create-sparc aigi command directly using the node executable. It covers creating a new project with a name or initializing in the current directory, emphasizing the omission of 'create-sparc' in the command.

```bash
node bin/index.js aigi init my-aigi-project

node bin/index.js aigi init
```

--------------------------------

### Authentication Error Response (HTTP/JSON)

Source: https://github.com/ruvnet/ruv-dev/blob/main/plans/mcp-registry-api-spec.md

Example HTTP 401 Unauthorized response body indicating an authentication failure, providing an error code and message.

```HTTP
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "unauthorized",
  "message": "Invalid or missing authentication token",
  "code": "AUTH_001"
}
```

--------------------------------

### Update MCP Server Interactively

Source: https://github.com/ruvnet/ruv-dev/blob/main/src/cli/commands/help/wizard.md

Start the interactive process to modify the configuration of an existing MCP server by specifying its server ID with the --update option.

```bash
create-sparc wizard --update openai
```

--------------------------------

### Set Environment Variable (Bash)

Source: https://github.com/ruvnet/ruv-dev/blob/main/src/cli/commands/help/wizard.md

Example command to set an environment variable in a Bash shell, often used for storing sensitive information like API keys.

```bash
export OPENAI_API_KEY=your_api_key_here
```