Atomize

Break down stories, build up velocity.

Atomize is a CLI tool that automatically generates granular tasks from user stories using YAML templates. Streamline your agile workflow with preset templates, story learning, and smart estimation distribution.

Features

• Preset Templates - Start with battle-tested templates for common workflows
• Story Learning - Generate templates by analyzing your existing work items (single or multiple stories)
• Pattern Detection - Identify common task patterns across multiple stories with confidence scoring
• Smart Estimation - Automatically distribute story points across tasks with conditional percentage support
• Strict & Lenient Validation - Flexible QA modes to enforce template quality
• Azure DevOps Integration - Native support with WIQL queries and full field mapping
• Zero Config - Works out of the box with sensible defaults
• Interactive Wizards - User-friendly prompts guide you through everything
• Built-in Validation - Catch template errors before they cause problems
• CI/CD Ready - Automation-friendly with JSON report output

Installation

Global Installation (Recommended)

npm install -g @sppg2001/atomize

Using npx (No Installation)

npx @sppg2001/atomize --help

Local Development

git clone https://github.com/Simao-Pereira-Gomes/atomize.git
cd atomize
bun install
bun run dev

Quick Start

1. Connect to Azure DevOps

# Add your first connection profile (interactive wizard)
atomize auth add work-ado

# Verify it works
atomize auth test work-ado

You'll be prompted for your Organization URL, project, team, and a Personal Access Token.

2. Generate Tasks from a Template

# Use a preset template (dry-run by default — safe to try)
atomize generate template:backend-api

# When ready to create tasks for real
atomize generate template:backend-api --execute

# Interactive mode (prompts for everything)
atomize generate

3. Create Your First Template

# From an existing template
atomize template create --from backend-api

# Learn from multiple stories (better pattern detection)
atomize template create --from-stories STORY-1,STORY-2,STORY-3

# Step-by-step wizard
atomize template create --scratch

4. Validate a Template

# Lenient mode (default) — only hard errors block use
atomize validate templates/my-template.yaml

# Strict mode — warnings also become errors
atomize validate templates/my-template.yaml --strict

Usage Guide

Generate Command

The generate command creates tasks in your work item management system based on a template.

# Basic usage
atomize generate template:backend-api

# With options
atomize generate template:backend-api \
  --platform azure-devops \
  --execute \
  --verbose

# Dry run (default — no --execute needed)
atomize generate template:backend-api

# CI/CD mode with JSON report
atomize generate template:backend-api \
  --execute \
  --auto-approve \
  --output report.json

Key Options:

• --platform <type> - Platform: azure-devops or mock
• --profile <name> - Named connection profile to use (see atomize auth add)
• --execute - Actually create tasks (default is dry-run preview)
• --auto-approve - Required with --execute in non-interactive mode to acknowledge live task creation
• --continue-on-error - Keep processing if errors occur
• --story-concurrency <n> - Parallel story processing (default: 3, max: 10)
• --task-concurrency <n> - Parallel task creation per story (default: 5, max: 20)
• --dependency-concurrency <n> - Parallel dependency link creation (default: 5, max: 10)
• --verbose - Show detailed output
• -o, --output <file> - Write JSON report to file
• --include-sensitive-report-data - Include descriptions, custom fields, and platform-specific work item data in the JSON report

In non-interactive mode, --execute now requires --auto-approve. This prevents unattended task creation from wrapper scripts or CI jobs that did not explicitly acknowledge the mutation.

Example Output:

✓ Loaded template: Backend API Development
✓ Found 3 matching user stories
✓ Generated 18 tasks (6 per story)
✓ Created 18 tasks in Azure DevOps

Summary:
  Stories processed: 3
  Tasks created: 18
  Execution time: 2.3s

Template Commands

Create a Template

# From an existing template (fastest)
atomize template create --from feature

# Learn from multiple stories (best pattern detection)
atomize template create \
  --from-stories STORY-1,STORY-2,STORY-3 \
  --save-as learned-api-template

# Interactive wizard (most control)
atomize template create --scratch

List Available Templates

atomize template list

Built-in Templates:

• backend-api - Backend API with database integration
• feature - General feature task workflow
• bug - Bug investigation and resolution workflow
• custom - Example template with custom fields
• custom-saved-query - Example template using an Azure DevOps saved query

Validate a Template

atomize validate templates/my-template.yaml

# Strict mode — warnings become errors (recommended for team/production templates)
atomize validate templates/my-template.yaml --strict

Template Structure

Templates are YAML files that define how to break down user stories into tasks.

Basic Template

version: "1.0"
name: "Backend API Development"
description: "Standard backend API workflow"

# Which stories to process
filter:
  workItemTypes: ["User Story"]
  states: ["New", "Active"]
  tags:
    include: ["backend", "api"]
  excludeIfHasTasks: true

# Task breakdown
tasks:
  - title: "Design API Endpoints: ${story.title}"
    description: "Design REST API endpoints and schemas"
    estimationPercent: 15
    activity: "Design"
    tags: ["design", "api"]

  - title: "Implement Core Logic: ${story.title}"
    description: "Implement business logic and validation"
    estimationPercent: 40
    activity: "Development"

  - title: "Write Tests"
    description: "Unit and integration tests"
    estimationPercent: 30
    activity: "Testing"

  - title: "Code Review & Documentation"
    description: "Review and document the implementation"
    estimationPercent: 15
    activity: "Documentation"

# Estimation settings
estimation:
  rounding: "nearest"
  minimumTaskPoints: 0.5

# Validation rules
validation:
  totalEstimationMustBe: 100
  minTasks: 3
  maxTasks: 10

Template Features

Variable Interpolation

- title: "Design: ${story.title}"
- description: "Story ${story.id}: ${story.description}"

Available variables: ${story.title}, ${story.id}, ${story.description}, ${story.estimation}, ${story.tags}

Task Assignment

assignTo: "@ParentAssignee"  # Inherit from story
assignTo: "@Me"              # Current user
assignTo: "[email protected]"   # Specific user

Conditional Tasks

- title: "Security Review"
  estimationPercent: 10
  condition:
    field: "tags"
    operator: "contains"
    value: "security"

Conditional Estimation (v1.1)

Adapt task percentage based on story properties. First matching rule wins; estimationPercent is the fallback.

- title: "Implementation"
  estimationPercent: 50                 # Default
  estimationPercentCondition:
    - condition:
        field: "tags"
        operator: "contains"
        value: "critical"
      percent: 60                       # More weight for critical stories
    - condition:
        field: "estimation"
        operator: "gte"
        value: 13
      percent: 55                       # More work for large stories

Task Dependencies

tasks:
  - id: "design"
    title: "Design Phase"
    estimationPercent: 20

  - id: "implement"
    title: "Implementation"
    estimationPercent: 60
    dependsOn: ["design"]   # Must complete design first

Platform Setup

Azure DevOps

1. Get a Personal Access Token (PAT)

   • Go to: https://dev.azure.com/[your-org]/_usersSettings/tokens
   • Create token with Work Items (Read, Write) scope

2. Save a connection profile

   atomize auth add work-ado
   # Prompts for org URL, project, team, and PAT

3. Test the connection

   atomize auth test work-ado

4. Generate tasks

   # Use the profile explicitly
   atomize generate template:backend-api --profile work-ado
   
   # Or set it as default once
   atomize auth use work-ado
   atomize generate template:backend-api

See atomize auth --help for all profile management commands (list, remove, rotate).

Mock Platform (Testing)

atomize generate template:backend-api --platform mock

No configuration required. Includes 7 built-in sample stories.

Strict vs Lenient Validation

Atomize has two validation modes:

| Mode | Warnings | Best For | |------|----------|----------| | Lenient (default) | Non-blocking | Development, personal templates | | Strict | Treated as errors | Team templates, CI/CD pipelines |

# Default (lenient) — only hard errors block use
atomize validate my-template.yaml

# Strict — warnings also fail validation
atomize validate my-template.yaml --strict

You can also set the mode in the template itself:

validation:
  mode: "strict"

Real-World Examples

Example 1: Backend API Feature

Story: "As a user, I want to reset my password via email"

Generated Tasks:

1. Design password reset flow and email templates (1.5 pts)
2. Implement password reset endpoint (3.5 pts)
3. Create email service integration (1.5 pts)
4. Write unit and integration tests (2 pts)
5. Add API documentation (0.5 pts)
6. Security review and rate limiting (1 pt)

Total: 10 story points perfectly distributed

Example 2: Multi-Story Learning

# Learn from your team's best stories
atomize template create \
  --from-stories STORY-100,STORY-115,STORY-132,STORY-148 \
  --platform azure-devops \
  --save-as backend-standard

# Validate the learned template
atomize validate template:backend-standard --strict

# Apply it
atomize generate template:backend-standard --execute

Advanced Usage

Custom Filters

filter:
  team: "Backend Team"                    # Override team from the selected profile
  workItemTypes: ["User Story", "Bug"]
  states: ["New", "Approved"]
  statesExclude: ["Done", "Removed"]      # Exclude items in these states
  statesWereEver: ["In Review"]           # Items that were ever in these states
  tags:
    include: ["backend"]
    exclude: ["deprecated"]
  areaPaths: ["MyProject\\Backend\\API"]  # Exact match
  areaPathsUnder: ["MyProject\\Backend"]  # Match and all sub-areas
  iterations: ["@CurrentIteration"]       # Current sprint
  iterationsUnder: ["MyProject\\Release 2"] # All sprints under a release
  assignedTo: ["@Me", "[email protected]"]
  changedAfter: "@Today-7"               # Changed in the last 7 days
  createdAfter: "@Today-30"              # Created in the last 30 days
  priority:
    min: 1
    max: 2
  excludeIfHasTasks: true
  customFields:
    - field: "Custom.Team"
      operator: "equals"
      value: "Platform Engineering"

Estimation Settings

estimation:
  strategy: "percentage"    # Distribute story points by percentage
  rounding: "nearest"       # nearest, up, down, none
  minimumTaskPoints: 0.5    # Minimum points per task
  ifParentHasNoEstimation: "skip"   # skip, warn, use-default

Environment Variables

| Variable | Description | Default | |---|---|---| | ATOMIZE_PROFILE | Default connection profile when --profile is not specified | (none) | | LOG_LEVEL | Log verbosity: error, warn, info, debug | warn |

macOS / Linux

Add to your shell profile (~/.zshrc, ~/.bashrc, etc.) and restart your terminal:

export ATOMIZE_PROFILE=work-ado   # Default connection profile
export LOG_LEVEL=warn             # Log verbosity (optional)

Windows (PowerShell)

To persist across sessions, set them as user environment variables:

[Environment]::SetEnvironmentVariable("ATOMIZE_PROFILE", "work-ado", "User")
[Environment]::SetEnvironmentVariable("LOG_LEVEL", "warn", "User")

Or for the current session only:

$env:ATOMIZE_PROFILE = "work-ado"
$env:LOG_LEVEL       = "warn"

Windows (Command Prompt)

For the current session only:

set ATOMIZE_PROFILE=work-ado
set LOG_LEVEL=warn

To persist, use System Properties → Environment Variables or setx:

setx ATOMIZE_PROFILE "work-ado"

Note: setx changes take effect in new terminal windows, not the current one.

Using --env-file for explicit file-based config

If you prefer file-based configuration (e.g. in CI/CD), pass --env-file explicitly:

# macOS / Linux
atomize --env-file ~/.config/atomize.env generate template:backend-api

# Windows (PowerShell)
atomize --env-file $env:USERPROFILE\.config\atomize.env generate template:backend-api

Shell environment variables always take precedence over values in the file, so it is safe to use --env-file as a fallback without risk of overriding real environment config.

See .env.example in the repository for a documented template.

Testing

# Run all tests
bun test

# Run specific test suite
bun test tests/unit/atomizer.test.ts

# Run with coverage
bun test --coverage

# Watch mode
bun test --watch

Development Setup

git clone https://github.com/Simao-Pereira-Gomes/atomize.git
cd atomize
bun install
bun run dev
bun test
bun run build

Troubleshooting

"Not authenticated" error

# Check what profiles are saved
atomize auth list

# Add a profile if none exist
atomize auth add work-ado

# Test the profile
atomize auth test work-ado

# Use it explicitly
atomize generate template:backend-api --profile work-ado

"Template validation failed"

# Get detailed output
atomize validate templates/my-template.yaml --strict

# Common issues:
# - Total estimation must equal 100%
# - Task dependencies reference non-existent IDs
# - Missing required fields

Documentation

• Getting Started - First steps and core concepts
• CLI Reference - Complete command and flag reference
• Template Reference - Full template schema
• Auth Guide - Credential storage, profiles, and CI/CD setup
• Validation Modes - Strict vs lenient explained
• Story Learner - Generate templates from existing stories
• Common Validation Errors - Fix validation failures
• Platform Guide - Azure DevOps setup
• Template Wizard Guide - Interactive wizard walkthrough

License

MIT License - see LICENSE file for details

Support

• Report a Bug
• Request a Feature
• Discussions