AI DevOps Framework

Common errors

• aidevops: command not found

  cause The aidevops CLI was not installed globally, or the installation directory is not in your system's PATH.
  fix Run `npm install -g aidevops` (or `brew install marcusquinn/tap/aidevops`) and ensure your shell's PATH includes the npm global bin directory. Restart your terminal if necessary.

• Error: Node.js version x.y.z is not supported. Please use Node.js >=18.0.0.

  cause Your current Node.js version does not meet the minimum requirement specified by the package.
  fix Upgrade your Node.js environment to version 18 or higher. Consider using `nvm` (Node Version Manager) to easily switch between Node.js versions: `nvm install 18 && nvm use 18`.

• API Key not found or invalid for AI provider: Anthropic

  cause The necessary API key for an underlying AI service (e.g., Claude via Anthropic) has not been set or is incorrect, preventing agents from making requests.
  fix Set the appropriate environment variable (e.g., `ANTHROPIC_API_KEY`) with a valid key, or configure it via `aidevops config set <key> <value>` if supported.

• Git command failed: fatal: working tree 'path/to/worktree' is missing or not a working tree

  cause A Git worktree managed by aidevops has been corrupted or manually removed, causing the framework to lose track of a project's state.
  fix Attempt to repair or re-initialize the worktree using `aidevops git repair` (if available) or manually recreate the project's state. In severe cases, you may need to re-initialize the project (`aidevops init`) and re-fetch changes.

Warnings

• gotcha The framework is primarily a CLI tool (`aidevops`) designed for global installation and direct command execution. It is not intended for direct programmatic import into JavaScript/TypeScript applications as a library. Interaction is exclusively via shell commands.
  Fix: Interact with aidevops through your terminal using `aidevops <command>`, or programmatically via Node.js `child_process` (as shown in the quickstart).
• breaking The `aidevops` framework, as an AI-driven system, is under continuous development. While semantic versioning is used, frequent minor releases (e.g., v3.8.x) may introduce behavioral changes to AI agents or workflows that, while not strictly API-breaking, might alter expected outcomes or require adjustments in prompts/configurations. Users should regularly review the `CHANGELOG.md` for detailed updates.
  Fix: Regularly run `aidevops update` to ensure you are on the latest stable version. Review the `CHANGELOG.md` (e.g., via `aidevops docs changelog`) before major deployments or critical AI tasks to understand recent changes.
• gotcha The framework relies heavily on external AI models (e.g., Claude, via OpenCode) and requires proper configuration of API keys and access. Misconfigured credentials or exceeding rate limits will lead to operational failures for AI agents.
  Fix: Ensure all necessary API keys for AI providers and OpenCode are correctly set in your environment or `aidevops` configuration. Monitor API usage and consult provider documentation for rate limits.
• gotcha The `aidevops` CLI requires Node.js >=18.0.0. Running with older Node.js versions may lead to unexpected errors or installation failures.
  Fix: Upgrade your Node.js environment to version 18 or higher using tools like `nvm` or your system's package manager.
• gotcha The `aidevops` framework creates and manages Git worktrees and branches for parallel agent execution. Incorrect manual manipulation of these Git structures outside of `aidevops` commands can lead to project inconsistencies or data loss.
  Fix: Always use `aidevops` commands for managing project workflows, branches, and worktrees. If manual Git intervention is necessary, proceed with caution and ensure you understand the framework's Git-first workflow implications.

Install

• npm install aidevops npm
• yarn add aidevops yarn
• pnpm add aidevops pnpm

Quickstart

This quickstart demonstrates how to install, update, and check the status of the AI DevOps Framework (aidevops) using its command-line interface, executed programmatically via Node.js's child_process.exec.

import { exec } from 'child_process';
import { promisify } from 'util';

const execPromise = promisify(exec);

async function runAideVopsQuickstart() {
  console.log('--- AI DevOps Framework Quick Start ---');

  // Ensure aidevops is installed globally (or install it)
  try {
    console.log('Checking aidevops installation...');
    await execPromise('npm install -g aidevops');
    console.log('aidevops installed or updated globally via npm.');
  } catch (error) {
    console.error(`Failed to install aidevops: ${error.message}`);
    return;
  }

  // Update the framework and any registered projects
  try {
    console.log('\nUpdating framework and projects...');
    const { stdout } = await execPromise('aidevops update');
    console.log(stdout);
  } catch (error) {
    console.error(`Failed to update aidevops: ${error.message}`);
  }

  // Check the status of the aidevops installation
  try {
    console.log('\nChecking aidevops status...');
    const { stdout } = await execPromise('aidevops status');
    console.log(stdout);
  } catch (error) {
    console.error(`Failed to get aidevops status: ${error.message}`);
  }

  // Initialize aidevops in a new or existing project directory
  // This would typically be run within a specific project's root.
  // For demonstration, we'll just show the command.
  console.log('\nTo initialize aidevops in a project, navigate to your project directory and run:');
  console.log('  aidevops init');
  console.log('\nTo list registered projects:');
  console.log('  aidevops list projects');

  console.log('\n--- Quick Start Complete ---');
}

runAideVopsQuickstart().catch(console.error);