### Install Dependencies and Start Dev Server

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/CONTRIBUTING.md

Run these commands to set up the development environment and start the local server.

```bash
bun install
bun dev
```

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

### Start Observability Stack

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/docker/observability/README.md

Run this command to start the observability stack using Docker Compose. Ensure you are in the 'docker/observability' directory.

```bash
cd docker/observability && docker compose up -d
```

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

### Start Observability Stack

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/docker/observability/README.md

Starts the local observability stack using Docker Compose. Ensure you are in the 'docker/observability' directory.

```bash
cd docker/observability
docker compose up -d
```

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

### Install CodeMachine CLI

Source: https://context7.com/moazbuilds/codemachine-cli/llms.txt

Install the CodeMachine CLI globally using npm or execute it directly with npx.

```bash
npm install -g codemachine
```

```bash
npx codemachine
```

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

### Install and Resolve Package Sources

Source: https://context7.com/moazbuilds/codemachine-cli/llms.txt

Use `resolveSource` to get a canonical URL for a package and `installPackage` to clone, validate, and register it. Import management functions like `getAllInstalledImports` and `unregisterImport` are also shown.

```typescript
import { resolveSource, installPackage } from 'codemachine/shared/imports';

// Resolve a source string to a canonical clone URL + repo name
const resolved = await resolveSource('myorg/codemachine-workflows');
// {
//   type: 'github',
//   url: 'https://github.com/myorg/codemachine-workflows.git',
//   repoName: 'codemachine-workflows',
//   owner: 'myorg'
// }

// Install a package (clone + validate + register)
const installResult = await installPackage('moazbuilds/my-workflows');
// { success: true, name: 'my-workflows', version: '1.0.0', path: '...' }
```

```typescript
import { getAllInstalledImports } from 'codemachine/shared/imports';
const packages = getAllInstalledImports();
for (const pkg of packages) {
  console.log(`${pkg.name} v${pkg.version} — ${pkg.source}`);
  // Resolved paths for templates, agents, prompts, etc.
  console.log(pkg.resolvedPaths.workflows);
  console.log(pkg.resolvedPaths.config);
}
```

```typescript
import { unregisterImport } from 'codemachine/shared/imports';
unregisterImport('my-workflows');
```

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

### Example Prompt Usage with Specification

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/chained/step-02-workflow-definition.md

Inject the specification file content into agent prompts using the `\{specification\}` placeholder.

```markdown
## Project Context

\{specification\}

## Your Task

Based on the above requirements, ...
```

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

### Create Manifest File Structure

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/quick-workflow.md

Example structure for a manifest file if it's missing. This file defines the workflow's name, version, description, and paths.

```json
{
  "name": "{workflow-name}",
  "version": "1.0.0",
  "description": "{description}",
  "paths": {
    "config": "config/",
    "workflows": "templates/workflows/",
    "prompts": "prompts/",
    "characters": "config/agent-characters.json"
  }
}
```

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

### Documentation Generator Workflow Example

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/chained/step-02-workflow-definition.md

Illustrates a documentation generation workflow using Hybrid Mode, where only the 'Doc Planner' and 'Final Reviewer' agents require user interaction.

```text
Scanner → auto → Analyzer → auto →
Planner → ⏸️ You approve outline → Enter →
Writer → auto →
Reviewer → ⏸️ You approve final docs → Done!
```

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

### CodeMachine Internal Structure Example

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/workflow.md

Illustrates the directory structure for a CodeMachine workflow, including configuration, templates, and prompt files.

```bash
~/.codemachine/imports/\{name\}-codemachine/
├── config/
│   ├── main.agents.js
│   ├── sub.agents.js (if needed)
│   ├── modules.js (if needed)
│   ├── placeholders.js (if shared content)
│   └── agent-characters.json
├── templates/workflows/
│   └── \{name\}.workflow.js
└── prompts/templates/\{name\}/
    ├── \{agent-name\}/
    │   ├── persona.md
    │   ├── workflow.md
    │   └── chained/
    │       ├── step-01.md
    │       └── step-02.md
    └── shared/

```

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

### Example Prompt with Placeholders

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/chained/step-02-workflow-definition.md

Use these built-in placeholders in your prompts to dynamically inject user selections and project context. Ali will inform users about these placeholders during prompt creation.

```markdown
You are working on a \{selected_track\} project.
The user has enabled these features: \{selected_conditions\}

Adapt your code generation accordingly.
```

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

### Start MCP Router with `codemachine mcp router`

Source: https://context7.com/moazbuilds/codemachine-cli/llms.txt

Starts the internal Model Context Protocol (MCP) router server over stdio. This is typically invoked automatically by engine adapters and not called directly by end users.

```bash
codemachine mcp router
```

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

### Code Review Workflow Example

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/chained/step-02-workflow-definition.md

Demonstrates a code review workflow in Hybrid Mode, highlighting agents that require user input for issue severity decisions and final approval.

```text
Diff Collector | `false` | Gathers code changes automatically
Issue Detector | `false` | Finds potential problems
Reviewer | `true` | **Shows issues - you decide severity**
Fix Suggester | `false` | Generates fix suggestions
Approver | `true` | **Final review - you approve/reject**
```

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

### Example Data Flow Between Agents

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/quick-workflow.md

Illustrates how data is passed from one agent to another using placeholders. Agent A writes to a file, which is then registered as a placeholder that Agent B can consume.

```text
Agent A → writes planner-output.md → registered as {planner_output}
Agent B → receives {planner_output} → builds on Agent A's work
```

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

### Install Workflow Packages with `codemachine import`

Source: https://context7.com/moazbuilds/codemachine-cli/llms.txt

Use `codemachine import` to install, update, list, or remove external workflow packages from GitHub, git URLs, or local directories. Installed packages make their templates and prompts discoverable.

```bash
codemachine import moazbuilds/my-workflows
```

```bash
codemachine import https://github.com/myorg/codemachine-workflows
```

```bash
codemachine import ./my-local-workflow-package
```

```bash
codemachine import /absolute/path/to/workflows
```

```bash
codemachine import git@github.com:myorg/workflows.git
```

```bash
codemachine import --list
```

```bash
codemachine import --remove my-workflows
```

```bash
codemachine import -v myorg/big-workflow-pack
```

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

### Continuous Mode Workflow Example

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/chained/step-02-workflow-definition.md

Illustrates the auto-advance behavior in Continuous Mode for sequential agents and chained prompts within an agent. Agents automatically proceed to the next step upon completion.

```text
Agent 1 → completes → auto-advance →
Agent 2 → completes → auto-advance →
Agent 3 → completes → Workflow Done!
```

```text
Agent 1 - Step 1 → auto-advance →
Agent 1 - Step 2 → auto-advance →
Agent 1 - Step 3 → completes → Next Agent...
```

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

### Display CodeMachine Version with `codemachine version`

Source: https://context7.com/moazbuilds/codemachine-cli/llms.txt

Use `codemachine version` to display the currently installed version of CodeMachine.

```bash
codemachine version
```

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

### Controller Definition Example

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/quick-workflow.md

Defines a controller for agent execution, specifying the engine and model to be used.

```javascript
controller: controller('controller-agent-id', {
  engine: 'claude',
  model: 'opus',
}),
```

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

### MCP Configuration for Step Agents

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/quick-workflow.md

Example MCP configuration for step agents when a controller is enabled, specifying the `workflow-signals` server and the tool for proposing step completion.

```json
{
  "server": "workflow-signals",
  "only": ["propose_step_completion"]
}
```

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

### Manage AI Engines with `registry`

Source: https://context7.com/moazbuilds/codemachine-cli/llms.txt

The `registry` singleton discovers and manages AI engine plugins. Use `getAllIds` to list available engines, `get` to retrieve a specific engine module, and `getDefault` for the highest-priority engine. You can directly execute tasks using an engine's `run` method, configuring parameters like model, working directory, and telemetry callbacks.

```typescript
import { registry } from 'codemachine/infra/engines';

// List all registered engine IDs
const ids = registry.getAllIds();
// ['opencode', 'claude', 'codex', 'cursor', 'mistral', 'auggie', 'ccr']

// Get a specific engine module
const claudeEngine = registry.get('claude');
if (claudeEngine) {
  const isAuthed = await claudeEngine.auth.isAuthenticated();
  console.log(`Claude authenticated: ${isAuthed}`);

  // Direct engine execution
  const result = await claudeEngine.run({
    prompt: 'Explain this codebase',
    workingDir: '/path/to/project',
    model: 'claude-opus-4-5',
    modelReasoningEffort: 'high',
    onData: (chunk) => process.stdout.write(chunk),
    onTelemetry: ({ tokensIn, tokensOut, cost }) =>
      console.log(`Cost: $${cost?.toFixed(4)}, tokens: ${tokensIn}/${tokensOut}`),
  });
}

// Get default (highest-priority) engine
const defaultEngine = registry.getDefault();
console.log(`Default engine: ${defaultEngine?.metadata.name}`);

// All metadata (useful for building engine-selection UIs)
const meta = registry.getAllMetadata();
// [{ id, name, description, cliCommand, cliBinary, defaultModel, order }, ...]
```

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

### Import and Use Workflow Helper Functions

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/quick-workflow.md

Import helper functions from './helpers.js' to define various workflow steps. Examples include basic and overridden agent steps, module steps with loop behavior, folder steps, visual separators, and controllers.

```javascript
import { resolveStep, resolveModule, resolveFolder, separator, controller } from './helpers.js';

// Basic agent step (engine/model from agent config)
resolveStep('agent-id')

// Agent step with overrides
resolveStep('agent-id', {
  engine: 'claude',
  model: 'opus',
  modelReasoningEffort: 'high',
  agentName: 'Custom Display Name',
  promptPath: './custom/prompt.md',
  executeOnce: true,
  interactive: false,
  tracks: ['track-id'],
  conditions: ['condition-id'],
})

// Module step with loop behavior
resolveModule('module-id', {
  loopSteps: 3,
  loopMaxIterations: 20,
  loopSkip: ['agent-to-skip'],
})

// Folder (loads all numbered files in order)
...resolveFolder('folder-name', { engine: 'codex' })

// Visual separator
separator('Phase Name')

// Controller
controller('controller-agent-id', {
  engine: 'claude',
  model: 'opus',
})
```

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

### MCP Configuration for Sub-agent Orchestration

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/quick-workflow.md

Example MCP configuration for parent agents orchestrating sub-agents, specifying the `agent-coordination` server and the tools for managing sub-agent execution.

```json
{
  "server": "agent-coordination",
  "only": ["run_agents", "get_agent_status", "list_available_agents"],
  "targets": ["sub-agent-1", "sub-agent-2"]
}
```

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

### Agent Filtering Configuration Example

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/chained/step-03-agents.md

Illustrates how agent and step-level filtering is defined using tracks and conditions in the agent configuration. Agent-level filters control when an agent runs, while step-level filters control when individual steps load.

```javascript
{
  id: 'ux-designer',
  tracks: ['frontend', 'fullstack'],  // Agent only runs for these tracks
  conditions: ['has_ui'],              // AND only if has_ui is selected
  chainedPromptsPath: [
    'step-01-discovery.md',            // Always loads
    { path: 'react-patterns.md', tracks: ['frontend'] },  // Only for frontend
    { path: 'mobile.md', conditions: ['has_mobile'] },    // Only if mobile
  ],
}
```

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

### MCP Configuration for Controller Agents

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/quick-workflow.md

Example MCP configuration for controller agents, specifying the `workflow-signals` server and the tools they can use for autonomous mode.

```json
{
  "server": "workflow-signals",
  "only": ["approve_step_transition", "get_pending_proposal"]
}
```

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

### Load Agent Configuration and Prompts

Source: https://context7.com/moazbuilds/codemachine-cli/llms.txt

Use `loadAgentConfig` to fetch agent settings and `loadAgentTemplate` to get the concatenated prompt string. Configuration is gathered from multiple sources, and errors are thrown for unknown agent IDs.

```typescript
import { loadAgentConfig, loadAgentTemplate } from 'codemachine/agents/runner';

// Load structured agent config
const config = await loadAgentConfig('cm-workflow-builder', '/path/to/project');
// {
//   id: 'cm-workflow-builder',
//   name: 'Ali | The CM Guy',
//   engine: 'claude',
//   model: 'claude-opus-4-5',
//   promptPath: ['/absolute/path/ali.md', '/absolute/path/workflow.md'],
//   chainedPromptsPath: [...],
// }

// Load + concatenate all prompt files into a single string
const promptString = await loadAgentTemplate('cm-workflow-builder', '/path/to/project');
// "# Ali - CodeMachine Workflow Builder\n\n…\n\n## Workflow Creation Guide\n…"
```

```typescript
try {
  await loadAgentConfig('nonexistent-agent', process.cwd());
} catch (err) {
  // Error: Unknown agent id: nonexistent-agent.
  // Available agents: cm-workflow-builder, cm-workflow-builder-quick
}
```

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

### Export Imports Directory Path with `codemachine export`

Source: https://context7.com/moazbuilds/codemachine-cli/llms.txt

Use `codemachine export` to get the path to the local imports directory where workflow packages are stored. This allows for direct filesystem access to installed packages.

```bash
codemachine export
```

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

### Package Management: resolveSource, installPackage, getAllInstalledImports, unregisterImport

Source: https://context7.com/moazbuilds/codemachine-cli/llms.txt

Functions for resolving, installing, listing, and removing package imports. These functions manage the local import registry and ensure packages are correctly installed and accessible.

```APIDOC
## resolveSource

### Description
Resolves a source string (GitHub shorthand, HTTPS URL, git SSH URL, or local path) to a canonical clone URL and repository name.

### Usage
```ts
import { resolveSource } from 'codemachine/shared/imports';

const resolved = await resolveSource('myorg/codemachine-workflows');
// Returns an object with type, url, repoName, and owner
```

## installPackage

### Description
Installs a package by resolving its source, cloning it into `~/.codemachine/imports/`, validating it, and registering it in the local registry.

### Usage
```ts
import { installPackage } from 'codemachine/shared/imports';

const installResult = await installPackage('moazbuilds/my-workflows');
// Returns an object with success status, name, version, and path
```

## getAllInstalledImports

### Description
Retrieves a list of all currently installed imports from the local registry.

### Usage
```ts
import { getAllInstalledImports } from 'codemachine/shared/imports';

const packages = getAllInstalledImports();
// Iterates over installed packages, providing name, version, source, and resolvedPaths
```

## unregisterImport

### Description
Removes a package from the local registry and its installation directory.

### Usage
```ts
import { unregisterImport } from 'codemachine/shared/imports';

unregisterImport('my-workflows');
```
```

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

### Initialize registry.json if it doesn't exist

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/quick-workflow.md

If the registry.json file is missing, create it with this basic structure to ensure proper workflow registration.

```json
{
  "schemaVersion": 1,
  "imports": {}
}
```

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

### View Docker Compose Service Logs

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/docker/observability/README.md

Retrieve logs for specific services within the Docker Compose setup to aid in troubleshooting.

```bash
docker compose logs tempo
docker compose logs loki
docker compose logs otel-collector
docker compose logs prometheus
docker compose logs grafana
```

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

### Module Configuration

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/ali.md

Sets up a reusable module within a workflow. Includes ID, name, description, prompt paths, and optional behavior like looping.

```javascript
{
  id: 'module-id',
  name: 'Module Name',
  description: 'Description',
  promptPath: 'path/to/prompt.md',
  chainedPromptsPath: ['array', 'of', 'paths'],
  behavior: {
    type: 'loop',
    action: 'stepBack',
  },
}
```

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

### Dynamic Sub-Agent Prompt Creation

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/chained/step-04-prompts.md

Instructions for creating a prompt file at runtime for dynamic sub-agents. This involves writing the prompt to a specific file path before invoking the sub-agent.

```bash
1. Write prompt to `.codemachine/agents/`{subAgent.id}`.md`
2. Then invoke the sub-agent using MCP or CLI
```

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

### Agent Coordination MCP Configuration

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/chained/step-03-agents.md

Configure the agent-coordination MCP for any main agent that needs to spawn or communicate with sub-agents. This is a required setup for inter-agent communication.

```javascript
mcp: [
  {
    server: 'agent-coordination',
    only: ['run_agents', 'get_agent_status', 'list_available_agents'],
    targets: ['{subAgent1.id}', '{subAgent2.id}', ...],
  },
]
```

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

### Create a Trace Search Panel

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/docker/observability/README.md

Configure a Tempo datasource table to display recent traces. Set the service name and limit the number of results for a focused view.

```json
{
  "datasource": "Tempo",
  "query": {
    "serviceName": "codemachine",
    "limit": 20
  },
  "visualization": "Table"
}
```

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

### Create an Application Logs Panel

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/docker/observability/README.md

Set up a Loki datasource logs panel to display application logs. Use a basic LogQL query to filter logs by service name.

```json
{
  "datasource": "Loki",
  "query": "{service_name=\"codemachine\"}",
  "visualization": "Logs"
}
```

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

### Run Codemachine Templates List Command

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/quick-workflow.md

Execute this command to list all registered workflows. This is the first step in verifying if your workflow is discoverable.

```bash
codemachine templates list
```

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

### MCP Tools for Sub-Agent Invocation

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/chained/step-04-prompts.md

Demonstrates how to invoke sub-agents using the MCP (Machine Command Protocol) tools. Includes commands for listing agents, running agents with scripts, and checking agent status.

```bash
1. list_available_agents - See available agents
2. run_agents { "script": "`{subAgent.id}` 'your task'" } - Execute
3. get_agent_status { "name": "`{subAgent.id}`" } - Check results
```

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

### Workflow Markdown Structure (Multi-step Agents)

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/quick-workflow.md

Defines the overall workflow for multi-step agents. This file is loaded at the start and provides context, rules, and an overview of the steps. It should not be included in `chainedPromptsPath`.

```markdown
---
name: '{agent.name} Workflow'
description: '{agent.description}'
---

{system_rules}

# {agent.name} Workflow

## YOUR MISSION

{agent's mission in the pipeline}

{if receives from previous agent}
## INPUT

You receive output from the previous agent:

{{{prev_agent}_output}}
{end if}

## STEP 0: GREET AND WAIT

This is your Step 0. You have NOT received your first working step yet.

**DISPLAY THIS MESSAGE:**

"{greeting message - introduce yourself, explain your role, list your steps}

Press **Enter** to start."

**THEN STOP. Do not start working. Wait for Enter.**

## WORKFLOW OVERVIEW

{table of steps}

## OUTPUT

{what this agent produces and where it writes it}

## RULES

{agent-specific rules}
```

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

### Persona Markdown Structure

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/quick-workflow.md

Defines the core persona for an agent, including its name, description, role, identity, communication style, and principles. This file is loaded at the start of an agent's execution.

```markdown
---
name: '{agent.name}'
description: '{agent.description}'
---

# {agent.name}

<persona>

## Role

{role based on agent purpose}

## Identity

{identity based on expected behavior}

## Communication Style

{style based on agent type}

## Principles

{principles to ensure quality output}

</persona>
```

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

### Example of Nested Conditions within Tracks

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/chained/step-02-workflow-definition.md

Demonstrates how conditions can be nested under a track to ask follow-up questions after a track is selected. This allows for more specific user input based on the chosen path.

```text
Track: modify (Modify Existing Workflow)
  └── Condition Group: "What do you want to modify?"
        ├── main-agents
        ├── sub-agents
        ├── modules
        └── prompts
```

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

### Create Codemachine Manifest (codemachine.json)

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/quick-workflow.md

This JSON file acts as a manifest for your workflow, specifying its name, version, description, and key paths for configuration, workflows, prompts, and characters.

```json
{
  "name": "{workflow-name}",
  "version": "1.0.0",
  "description": "{workflow description}",
  "paths": {
    "config": "config/",
    "workflows": "templates/workflows/",
    "prompts": "prompts/",
    "characters": "config/agent-characters.json"
  }
}
```

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

### Registry File Structure (registry.json)

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/quick-workflow.md

Defines the central registry of installed workflow imports. This JSON structure is located at `~/.codemachine/imports/registry.json` and must contain an entry for `codemachine templates list` to find your workflow.

```json
{
  "schemaVersion": 1,
  "imports": {
    "workflow-name": {
      "name": "workflow-name",
      "version": "1.0.0",
      "source": "workflow-name-codemachine",
      "path": "/home/user/.codemachine/imports/workflow-name-codemachine",
      "installedAt": "2024-01-15T10:30:00.000Z",
      "resolvedPaths": {
        "config": "/home/user/.codemachine/imports/workflow-name-codemachine/config",
        "workflows": "/home/user/.codemachine/imports/workflow-name-codemachine/templates/workflows",
        "prompts": "/home/user/.codemachine/imports/workflow-name-codemachine/prompts",
        "characters": "/home/user/.codemachine/imports/workflow-name-codemachine/config/agent-characters.json"
      }
    }
  }
}
```

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

### Configure Agents with Prompts and Chained Prompts

Source: https://context7.com/moazbuilds/codemachine-cli/llms.txt

Define agents in `main.agents.js` with their IDs, names, and prompt paths. Use `chainedPromptsPath` for multi-phase agents, specifying conditions for loading different prompt files.

```javascript
// config/main.agents.js
const path = require('node:path');
const promptsDir = path.join(__dirname, '..', 'prompts', 'templates');

module.exports = [
  {
    id: 'code-reviewer',
    name: 'Code Reviewer',
    description: 'Reviews diffs and suggests improvements',
    engine: 'claude',
    model: 'claude-opus-4-5',
    promptPath: path.join(promptsDir, 'reviewer', 'reviewer.md'),
  },

  // Multi-phase agent with conditional chained prompts
  {
    id: 'cm-workflow-builder',
    name: 'Ali | The CM Guy',
    description: 'Builds CM workflows in 5 guided steps',
    promptPath: [
      path.join(promptsDir, 'ali', 'ali.md'),
      path.join(promptsDir, 'ali', 'workflow.md'),
      path.join(promptsDir, 'ali', 'chained', 'step-00-setup.md'),
    ],
    chainedPromptsPath: [
      // conditionsAny: step fires when any of these conditions are selected
      { path: path.join(promptsDir, 'ali', 'chained', 'step-01-brainstorming.md'),
        conditionsAny: ['full-workflow', 'brainstorming'] },
      { path: path.join(promptsDir, 'ali', 'chained', 'step-02-workflow-definition.md'),
        conditionsAny: ['full-workflow', 'workflow-definition'] },
      { path: path.join(promptsDir, 'ali', 'chained', 'step-03-agents.md'),
        conditionsAny: ['full-workflow', 'agents'] },
    ],
  },
];

```

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

### Placeholders Configuration

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/quick-workflow.md

Defines path placeholders for user directories and package directories.

```javascript
const path = require('node:path');

module.exports = {
  // User directory placeholders (resolved from user's project root)
  userDir: {
    agent_output: path.join('.codemachine', 'artifacts', 'agent-output.md'),
    specification: path.join('.codemachine', 'specification.md'),
  },

  // Package directory placeholders (resolved from CodeMachine installation)
  packageDir: {
    shared_rules: path.join('prompts', 'templates', 'workflow-name', 'shared', 'rules.md'),
    common_patterns: path.join('prompts', 'templates', 'workflow-name', 'shared', 'patterns.md'),
  },
};
```

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

### Register Workflow in registry.json

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/quick-workflow.md

This JavaScript pseudocode demonstrates how to read the existing registry.json, add your new workflow's details, and write the updated registry back. Ensure the registry file exists or is created.

```javascript
// Pseudocode for registration
const registryPath = '~/.codemachine/imports/registry.json';
const registry = JSON.parse(fs.readFileSync(registryPath));

const workflowPath = `~/.codemachine/imports/{workflow-name}-codemachine`;

registry.imports['{workflow-name}'] = {
  name: '{workflow-name}',
  version: '1.0.0',
  source: '{workflow-name}-codemachine',
  path: workflowPath,  // Absolute path
  installedAt: new Date().toISOString(),
  resolvedPaths: {
    config: `${workflowPath}/config`,
    workflows: `${workflowPath}/templates/workflows`,
    prompts: `${workflowPath}/prompts`,
    characters: `${workflowPath}/config/agent-characters.json`
  }
};

fs.writeFileSync(registryPath, JSON.stringify(registry, null, 2));
```

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

### Troubleshoot Missing Manifest File

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/quick-workflow.md

If the workflow is not found, check if its manifest file exists in the expected location. If missing, create it with the correct structure.

```bash
cat ~/.codemachine/imports/{workflow-name}-codemachine/codemachine.json
```

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

### Module Step with Trigger Behavior

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/chained/step-05-workflow-generation.md

Sets up a module step to trigger another agent. Use this for orchestrating sub-agent calls.

```javascript
module: {
  id: 'trigger-agent',
  behavior: {
    type: 'trigger',
    action: 'mainAgentCall',
    triggerAgentId: 'sub-agent-id',
  }
}
```

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

### Generate Main Prompt File

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/chained/step-04-prompts.md

This markdown structure is used to generate the `prompt.md` file for an agent. It includes sections for context, goal, instructions, sub-agent coordination, output, and success criteria.

```markdown
---
name: '`{agent.name}` Prompt'
description: '`{agent.description}`'
---

# `{agent.name}`

`{if receives from previous agent}`
## CONTEXT

`{{`{prev_agent}`_output}}`
`{end if}`

`{if has other placeholders}`
`{for each placeholder}`
`{{`{placeholder_name}`}}`
`{end for}`
`{end if}`

## GOAL

`{goal from description/expectedBehavior}`

## INSTRUCTIONS

`{for each instruction}`
- `{instruction}`
`{end for}`

`{if has sub-agents}`
## SUB-AGENT COORDINATION

You can invoke the following sub-agents during execution:

`{for each subAgent of this agent}`
### `{subAgent.name}` (`{subAgent.id}`)

**Description:** `{subAgent.description}`
**Type:** `{Static (pre-defined prompt) | Dynamic (you generate at runtime)}`
`{if static}`
**Trigger:** When you need `{subAgent.expectedOutput}`
`{end if}`
`{if dynamic}`
**Trigger Condition:** `{subAgent.triggerCondition}`
**Generation Instructions:** `{subAgent.generationInstructions}`
`{end if}`

`{end for}`

### How to Invoke Sub-Agents

**Option 1: MCP Tools (Recommended)**
```
1. list_available_agents - See available agents
2. run_agents { "script": "`{subAgent.id}` 'your task'" } - Execute
3. get_agent_status { "name": "`{subAgent.id}`" } - Check results
```

**Option 2: CLI Syntax**
```bash
codemachine run "`{subAgent.id}`[options] 'your task'"
```

**Options:**
- `input:file.md` - Pass file content to sub-agent
- `input:f1.md;f2.md` - Multiple input files
- `tail:100` - Limit output lines

**Orchestration Patterns:**
- `&` - Run sub-agents in parallel (independent tasks)
- `&&` - Run sequentially (output feeds next)
- `a && b & c` - a first, then b and c in parallel

`{if has dynamic subAgents}`
### Dynamic Sub-Agent Generation

For dynamic sub-agents, create the prompt file at runtime:
1. Write prompt to `.codemachine/agents/`{subAgent.id}`.md`
2. Then invoke the sub-agent using MCP or CLI
`{end if}`

`{end if}`

## OUTPUT

`{agent.output}`

`{if outputs to next agent}`
**Write output to:** `.codemachine/artifacts/`{agent.id}`-output-*.md`
`{end if}`

## SUCCESS CRITERIA

`{agent.successIndicators}`
```

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

### Agent Step Configuration

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/chained/step-05-workflow-generation.md

Defines an agent step with properties like agent ID, prompt path, and optional model overrides. Use this for direct agent interactions.

```javascript
resolveStep('agent-id')
```

```javascript
resolveStep('agent-id', {
  engine: 'claude',
  model: 'opus',
  modelReasoningEffort: 'high',
  agentName: 'Custom Name',
  promptPath: './custom/prompt.md',
  executeOnce: true,
  interactive: false,
  tracks: ['track-id'],
  conditions: ['condition-id'],
})
```

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

### Create a Log Volume Panel

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/docker/observability/README.md

Configure a Loki datasource time series panel to visualize log volume by severity. This query aggregates log counts over 1-minute intervals.

```logql
sum by (severity_text) (count_over_time({service_name="codemachine"}[1m]))
```

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

### Run Workflow Command

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/prompts/templates/ali/quick-workflow.md

Use this command to execute your generated workflow. Replace `{workflow-name}` with the actual name of your workflow.

```bash
codemachine workflow {workflow-name}
```

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

### Run Full CLI for Testing

Source: https://github.com/moazbuilds/codemachine-cli/blob/main/docker/observability/README.md

Executes the main CLI command with tracing and logging enabled to send test data to the observability stack. This is an alternative to running the embedded script.

```bash
DEBUG=true CODEMACHINE_TRACE=2 CODEMACHINE_TRACE_EXPORTER=otlp \
  CODEMACHINE_TRACE_OTLP_ENDPOINT=http://localhost:4319/v1/traces \
  bun run dev --help
```