iterate

iterate - AI-Powered Iterative Task Completion

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.

Overview#

The iterate command implements a “loop until done” pattern:

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

Commands#

iterate run#

Run the iterative task completion loop.

Syntax:

nmbl iterate [run] [iterations] [options]

Arguments:

• iterations - Maximum number of iterations (default: 10)

Options:

• --agent <name> - AI agent to use: copilot-sdk (default), copilot-cli, or claude-cli
• --model <name> - Model to use (agent-specific, use ? for interactive selection)
• --input <path> - Directory containing prompt.md, requirements.md, progress.md
• --workspace <path> - Directory where agent creates/modifies work files (default: ./work/)

Examples:

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

# Run with explicit iteration count
nmbl iterate run 20

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

# Interactive model selection
nmbl iterate run --model ?

# Specify custom directories
nmbl iterate run --input ./.iterate --workspace ./output

iterate setup#

Initialize a workspace with the required markdown files for iteration.

Syntax:

nmbl iterate setup [options]

Options:

• --dir <path> - Target directory for setup files (default: ./.iterate/)
• --from <file> - Use an existing file as requirements.md
• --issue <number> - Fetch requirements from a GitHub issue
• --repo <owner/repo> - GitHub repository for issue (default: current repo)
• --force - Overwrite existing files

Examples:

# Create .iterate folder with default files
nmbl iterate setup

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

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

# Fetch requirements from GitHub issue
nmbl iterate setup --issue 123

# Fetch from specific repository
nmbl iterate setup --issue 456 --repo owner/repo-name

# Overwrite existing files
nmbl iterate setup --force

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

Input Directory vs Workspace#

File Descriptions#

Supported Agents#

Exit Codes#

Workflow Example#

# 1. Setup workspace with requirements from a GitHub issue
nmbl iterate setup --issue 42

# 2. (Optional) Review/edit the generated files
code .iterate/requirements.md

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

# 4. Check results in ./work/ directory

Tips#

• Start with fewer iterations - Use 5-10 iterations 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
• Customize prompt.md - Modify the agent instructions for your specific use case
• Use --model ? - Interactive model selection helps discover available models