CodeMachine CLI

When creating workflows in CodeMachine, agents are organized into specific folder structures based on their complexity. Every workflow template resides in prompts/templates/{workflow_name}/ and must include a shared/system-rules.md file.

Single-step Agents

Used for simple, one-off tasks. They require two files:

• persona.md: Defines the agent's role and identity.
• prompt.md: Contains the core instructions and goals.

Multi-step (Chained) Agents

Used for complex workflows where tasks are broken down. They require:

• persona.md: Defines the agent's role.
• workflow.md: Defines the high-level orchestration.
• chained/: A directory containing sequential steps (e.g., step-01-{purpose}.md, step-02-{purpose}.md).

Other Components

• Controllers: Use persona.md and prompt.md.
• Static Sub-Agents: Use mirror.md to reflect parent configurations.
• Modules: Follow the multi-step structure (persona.md, workflow.md, and chained/ steps).

prompts/templates/{workflow_name}/
├── shared/
│   └── system-rules.md           ← REQUIRED
├── {agent-id}/
│   ├── persona.md
│   ├── prompt.md                 (if single-step)
│   ├── workflow.md               (if multi-step)
│   └── chained/
│       ├── step-01-{purpose}.md
│       └── step-02-{purpose}.md

Autonomous Mode (Beta) uses a Controller Agent to handle agent-to-agent interactions automatically.

Key Features:

• Briefing: You provide project goals and constraints to the controller once at the start.
• Automatic Responses: The controller distinguishes between USER and AGENT_NAME messages to respond appropriately.
• Toggling: Use Shift+Tab during execution to switch between Manual (you respond) and Autonomous (controller responds) modes.
• Direct Access: Press R at any time to talk to the controller directly.

Configuration Options for autonomousMode: When controller: true is set in your workflow file, you must define the starting behavior via autonomousMode:

• 'never': Always manual; autonomous mode is disabled.
• 'always': Always autonomous; cannot switch to manual.
• false: Starts in manual mode; can be enabled via Shift+Tab.
• true: Starts in autonomous mode; can be switched to manual via Shift+Tab.

CodeMachine workflows operate using three distinct runner modes that determine how the system interacts with users and handles prompts. These modes are mapped to specific behaviors called 'Scenarios'.

Runner Modes

• Interactive: The system waits for input from either a user or a controller.
• Autonomous: The system is fully automated and sends all prompts without waiting.
• Continuous: The system automatically advances to the next step without prompting.

Scenarios Reference

Every workflow must include a shared/system-rules.md file. This file is critical as it teaches all agents the fundamental mechanics of the CodeMachine Workflow System.

Core System Concepts for Agents:

• Pipeline Model: Agents exist in a pipeline (e.g., Agent1 → Agent2) and do not control the flow; the system does.
• Chained Prompts: Agents receive instructions one step at a time.
• Step Transitions: Agents must not advance steps themselves. When a step is complete, the agent must instruct the user to "Press Enter to continue." and then STOP completely. The system then injects the next step.
• Step 0: The initial prompt (persona + workflow) is 'Step 0'. The agent's first task is to introduce itself and say "Press Enter to start."

Critical Rules:

• Complete only the current step.
• Do not combine steps.
• Do not perform tasks belonging to other agents.
• Follow output file paths and formats exactly as specified.

# SYSTEM RULES (READ BEFORE ANYTHING ELSE)

You are an agent inside the **CodeMachine Workflow System**. You do NOT control the flow. The system does.

## HOW THE SYSTEM WORKS

1. You are **one agent** in a pipeline of {N} agents: **{Agent1} → {Agent2} → ... → {AgentN}**
2. Each agent has **multiple steps** (chained prompts). You receive them one at a time
3. **You do NOT advance steps yourself.** The system injects the next step when the user presses Enter
4. **You do NOT decide when to move on.** You complete your current step, tell the user to press Enter, and STOP

## YOUR STEPS

When you start, you are on **Step 0** (this prompt). You have NOT received your first step yet.

| What You See | What It Means |
|-------------|---------------|
| This prompt (persona + workflow) | **Step 0** - You just arrived. Greet the user and explain what you'll do |
| A new prompt injected after user presses Enter | **Step 1, 2, 3...** - The system gave you your next step. Execute it |

## STEP 0: WHAT TO DO RIGHT NOW

Your first action is to introduce yourself and explain your role in the pipeline.
Then say "Press **Enter** to start." and STOP. Do not do anything else.

## CRITICAL RULES FOR EVERY STEP

### Rule 1: One Step at a Time
- Complete ONLY what that step asks for
- Do NOT do work from future steps
- Do NOT combine steps

### Rule 2: You Do NOT Control Step Transitions
- When a step is complete, tell the user: **"Press Enter to continue."**
- Then **STOP COMPLETELY**
- The system will inject the next step's prompt

### Rule 3: Stay In Your Lane
- You are ONE agent. Do not do another agent's job
{list each agent and their lane}

### Rule 4: The Prompt IS Your Instructions
- Follow the prompt's instructions exactly as written
- Display the exact messages it tells you to display
- Do NOT improvise or add your own messages

### Rule 5: Output Files Are Sacred
- Write output files EXACTLY as specified in the step
- Use the EXACT file path and format given
- Do NOT write output before the step tells you to

## FORBIDDEN BEHAVIORS
- Starting work before your first step prompt arrives
- Doing multiple steps in one response
- Skipping the "press Enter" instruction at the end of a step
- Working on things outside your agent's scope
- Improvising messages instead of following the script

CodeMachine workflows operate in one of three modes, which determine how much control you have versus how much automation is applied. Choosing the right mode depends on whether you want to guide the process step-by-step, run a fully automated pipeline, or mix both for efficiency.

1. Manual Mode (Human as Orchestrator)

In Manual Mode, you control the pace. The agent performs a step, then waits for your response. You must press Enter to proceed to the next step or the next agent.

• Best for: Repetitive tasks that require human insight, brainstorming, or quality-critical workflows where you review every output.
• Technical configuration:
  • autonomousMode: 'never'
  • Usually does not require a specification file (you provide context via conversation).

2. Continuous Mode (Fully Automated)

In Continuous Mode, the workflow runs from start to finish without pausing. Agents complete their tasks and the system automatically advances to the next agent or chained prompt.

• Best for: Tasks that don't need human input, such as batch processing, generating reports from existing data, or running established pipelines.
• Technical configuration:
  • autonomousMode: 'always' (or true to allow manual pausing via Shift+Tab).
  • All agents must have interactive: false.
  • Requires a specification file (e.g., a PRD or brief) to provide the necessary context since there is no human interaction.

3. Hybrid Mode (Mix Auto & Interactive)

Hybrid Mode allows you to define interactivity on a per-agent basis. You can automate data-gathering agents while forcing the workflow to pause for human judgment at specific decision points.

• Best for: Workflows with clear

Agent 1 (Analyzer) [interactive: false]  → Scans codebase automatically → auto-advance →

Agent 2 (Planner) [interactive: true]     → Proposes plan → ⏸️ WAITS for your feedback →

Agent 3 (Generator) [interactive: false] → Generates output automatically → auto-advance →

Agent 4 (Reviewer) [interactive: true]    → Shows results → ⏸️ WAITS for approval →

Agents in a workflow are isolated. To enable collaboration, you must explicitly define how data flows between them using placeholders.

Input Sources

Agents can receive context from:

• Built-in variables: {date}, {project_name}, {selected_track}, {selected_conditions}.
• Spec files: {specification} (if enabled).
• Shared files: Templates, rules, or reference docs.
• Previous Agent Output: Chaining the output of a preceding agent.

Output Registration

To pass data to the next agent, an agent must produce an output file. This file is registered as a placeholder for the subsequent agent.

Example Pattern:

1. Agent A writes to .codemachine/artifacts/agent-a-output.md.
2. This is registered as the placeholder {agent_a_id}_output.
3. Agent B receives {agent_a_id}_output in its prompt context.

Data Flow Model

{agent1} → writes {output-file} → registered as {placeholder}
     ↓
{agent2} → receives {placeholder} → writes {output-file} → registered as {placeholder}

Tracks allow you to create different paths through the same workflow. When a workflow starts, a modal appears requiring the user to select a track. This is useful for handling different environments (e.g., JavaScript vs. Python) or different intents (e.g., Create vs. Modify) within a single persona.

Key Characteristics:

• Shared vs. Specific Steps: You can define steps that run for all tracks (shared) and steps that run only for specific tracks.
• Track Selection: Users MUST select a track to proceed.
• Agent Assignment: You assign specific agents to run only when a particular track is active.
• Track Definition Format: When defining tracks, use the format: id | label | description (e.g., javascript | JavaScript Project | For Node.js or React projects).
• Runtime Awareness: Agents can access the selected track using the {selected_track} placeholder in their prompts.