iterate

Overview

The iterate command automates multi-step task completion using AI agents. It runs an AI agent in a loop, completing one task per iteration until all requirements are met or a maximum iteration count is reached.

Each iteration follows this pattern:

Reads task requirements from requirements.md
Checks current progress from progress.md
Invokes an AI agent to complete ONE task per iteration
Agent updates progress.md after each task
Continues looping until finished or max iterations reached
Reports final status and iteration count

Commands

iterate setup

Initialize a workspace with the required markdown files for iteration.

Syntax:

nmbl iterate setup [directory] [sourceFile] [issueNumber] [repository] [force]

Positional arguments (all optional):

directory — target workspace directory. Defaults to ./.iterate/ in the current directory.
sourceFile — path to a local file to use as requirements.md.
issueNumber — GitHub issue number to fetch as requirements.
repository — owner/repo when fetching a GitHub issue from a specific repository.
force — pass true to overwrite existing workspace files.

Note: --from, --issue, --repo, and --force shown in some contexts are the conceptual names for these positional slots. The command accepts them as positional arguments in the order listed above.

Constraints:

sourceFile and issueNumber are mutually exclusive — you cannot supply both.
repository requires issueNumber to also be specified.

Exit codes:

0 — workspace created successfully.
1 — argument validation failed, source file could not be read, directory creation failed, or workspace files already exist without force being set.

Examples:

# Create .iterate folder with default placeholder requirements
nmbl iterate setup

# Create in a custom directory
nmbl iterate setup ./my-tasks

# Use an existing local requirements file
nmbl iterate setup ./.iterate ./specs/feature-spec.md

# Fetch requirements from GitHub issue #123 (current repo)
nmbl iterate setup ./.iterate "" 123

# Fetch from a specific GitHub repository
nmbl iterate setup ./.iterate "" 456 owner/repo-name

# Overwrite existing workspace files
nmbl iterate setup ./.iterate "" "" "" true

iterate run

Run the iterative task completion loop.

Syntax:

nmbl iterate run [maxIterations] [agent] [model] [inputDir] [workspaceDir]

Positional arguments (all optional):

maxIterations — maximum number of agent iterations. Defaults to 10.
agent — agent strategy identifier. Defaults to copilot-sdk. Accepted values: copilot-sdk, copilot-cli, claude-cli.
model — model name to pass to the agent. Pass ? for interactive model selection. Defaults to the agent strategy’s default model.
inputDir — path to the directory containing prompt.md and requirements.md. Auto-resolved if omitted.
workspaceDir — path where the agent creates or modifies work files. Defaults to ./work.

Input directory resolution (when inputDir is omitted):

./.iterate/ in the current directory, if it exists.
The current directory as a fallback.

Exit codes:

0 — Agent reported <result>finished</result> — all requirements complete.
1 — Configuration or input-directory error, or agent initialization failed.
2 — Agent process exited with a non-zero code.
3 — Agent output did not contain a valid <result> tag.
5 — Maximum iteration count reached without the agent completing.

Examples:

# Run with defaults (10 iterations, copilot-sdk agent)
nmbl iterate run

# Run with a higher iteration limit
nmbl iterate run 20

# Use the Claude CLI agent
nmbl iterate run 10 claude-cli

# Use a specific model
nmbl iterate run 10 copilot-sdk gpt-4o

# Interactive model selection
nmbl iterate run 10 copilot-sdk ?

# Specify custom input and workspace directories
nmbl iterate run 10 copilot-sdk "" ./.iterate ./output

Directory Structure

The `.iterate` folder

The .iterate folder is the recommended way to organize iteration files:

project/
├── .iterate/
│   ├── prompt.md        # Instructions for the AI agent
│   ├── requirements.md  # Tasks to complete
│   ├── progress.md      # Log of completed work (updated by agent)
│   └── work/            # Workspace where agent creates files

File descriptions

File	Purpose	Modified by
`prompt.md`	Instructions for the AI agent	You (customize if needed)
`requirements.md`	Tasks to complete	You (or seeded via setup)
`progress.md`	Log of completed work	AI agent (appends after each task)

Supported Agents

Agent	Description	Requirements
`copilot-sdk`	GitHub Copilot SDK (default)	GitHub Copilot subscription
`copilot-cli`	GitHub Copilot CLI	`gh copilot` extension installed
`claude-cli`	Anthropic Claude CLI	`claude` CLI installed

Workflow Example

# 1. Set up the workspace, seeding requirements from a GitHub issue
nmbl iterate setup ./.iterate "" 42

# 2. Review and edit the generated files if needed
# (Edit .iterate/requirements.md as appropriate)

# 3. Run the iteration loop
nmbl iterate run 15 copilot-sdk

# 4. Check the results in ./.iterate/work/

Tips

Start with fewer iterations — use 5–10 initially to verify the agent understands the requirements.
Use specific requirements — break down tasks into clear, atomic steps in requirements.md.
Review progress.md — check the progress log to understand what the agent has completed each iteration.
Customize prompt.md — modify the agent instructions to suit your specific use case.
Use ? as the model — interactive model selection helps discover available models for your chosen agent.