Skip to main content
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
A minimum workflow requires only three files: codemachine.json, main.agents.js, and a .workflow.js file. Everything else is optional.

​
Required Files

FileLocationPurpose
codemachine.jsonRootPackage manifest with name and version
main.agents.jsconfig/Main agent definitions
*.workflow.jstemplates/workflows/Workflow step definitions

​
Optional Files

FileLocationPurpose
sub.agents.jsconfig/Sub-agent definitions for orchestrated agents
modules.jsconfig/Module definitions for looping agents
placeholders.jsconfig/Dynamic content placeholders
agent-characters.jsonconfig/Agent personalities and display styles
prompts/RootPrompt 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"
}
FieldRequiredDescription
nameYesPackage identifier (used for imports)
versionYesSemantic version (e.g., 1.0.0)
descriptionNoBrief 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"
}

​
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