Package Structure

A workflow package is a folder containing everything CodeMachine needs to run your workflow: configuration, prompts, and workflow definitions.

New to building workflows? Use the built-in Ali workflow for step-by-step guidance.

Folder Structure

Every workflow package follows this structure:

my-workflow-codemachine

codemachine.json

config

main.agents.js

sub.agents.js

modules.js

placeholders.js

agent-characters.json

templates

workflows

example.workflow.js

prompts

A minimum workflow requires only three files: codemachine.json, main.agents.js, and a .workflow.js file. Everything else is optional.

Required Files

File	Location	Purpose
`codemachine.json`	Root	Package manifest with name and version
`main.agents.js`	`config/`	Main agent definitions
`*.workflow.js`	`templates/workflows/`	Workflow step definitions

Optional Files

File	Location	Purpose
`sub.agents.js`	`config/`	Sub-agent definitions for orchestrated agents
`modules.js`	`config/`	Module definitions for looping agents
`placeholders.js`	`config/`	Dynamic content placeholders
`agent-characters.json`	`config/`	Agent personalities and display styles
`prompts/`	Root	Prompt templates for agents

Manifest File

Every workflow package must have a codemachine.json manifest at its root:

codemachine.json

{
  "name": "my-workflow",
  "version": "1.0.0",
  "description": "Optional description of your workflow"
}

Field	Required	Description
`name`	Yes	Package identifier (used for imports)
`version`	Yes	Semantic version (e.g., `1.0.0`)
`description`	No	Brief description of your workflow

The name field must be unique. When importing, CodeMachine uses this to identify the package.

Real Examples

{
  "name": "bmad",
  "version": "1.0.0",
  "description": "BMAD Method - Business-driven Modular Agile Development workflow for greenfield projects"
}

{
  "name": "codemachine-one",
  "version": "1.0.0",
  "description": "CodeMachine-One autonomous development workflow - from specification to implementation"
}

Importing Packages

Once your package has a valid manifest, you can import it using the CLI or TUI:

codemachine import ./path/to/workflow

Or from within CodeMachine:

/import ./path/to/workflow

Import Workflows

Learn about all import sources: local paths, GitHub repos, and more

Next Steps

Build Agents

Learn how to configure agents in main.agents.js

Build Workflows

Configuration

Share Workflows

Folder Structure

Required Files

Optional Files

Manifest File

Real Examples

Importing Packages

Import Workflows

Next Steps

Build Agents

​Folder Structure

​Required Files

​Optional Files

​Manifest File

​Real Examples

​Importing Packages

Import Workflows

​Next Steps

Build Agents

Folder Structure

Required Files

Optional Files

Manifest File

Real Examples

Importing Packages

Next Steps