@sppg2001/atomize 1.0.3 → 1.2.0

package/.env.example

@@ -1,3 +1,17 @@
-AZURE_DEVOPS_ORG_URL=https://dev.azure.com/your-org
-AZURE_DEVOPS_PROJECT=YourProject
-AZURE_DEVOPS_PAT=your-personal-access-token
+# Atomize environment variables
+#
+# These can be set in your shell profile (~/.zshrc, ~/.bashrc) or passed
+# explicitly via: atomize --env-file /path/to/.env <command>
+#
+# Shell environment always takes precedence over --env-file values.
+
+# Personal Access Token used by `atomize auth add` when running non-interactively.
+# Prefer setting this in your CI/CD platform's secrets store rather than a .env file.
+# ATOMIZE_PAT=your-personal-access-token
+
+# Default connection profile to use when --profile is not specified.
+# Run `atomize auth list` to see available profiles.
+# ATOMIZE_PROFILE=work-ado
+
+# Winston log level: error, warn, info, debug (default: warn).
+# LOG_LEVEL=warn

package/README.md

@@ -7,27 +7,28 @@
 [![Node Version](https://img.shields.io/node/v/@sppg2001/atomize)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
 
-
 **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 AI-powered task breakdowns, preset templates, and smart estimation distribution.
+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
+## Features
 
-- **🤖 AI-Powered Generation** - Create templates using Google Gemini or local Ollama (completely free)
-- **📋 Preset Templates** - Start with battle-tested templates for common workflows
-- **🧠 Story Learning** - Generate templates by analyzing your existing work items
-- **🎯 Smart Estimation** - Automatically distribute story points across tasks
-- **🔗 Azure DevOps Integration** - Native support with more platforms coming soon
-- **⚡ 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
+- **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
+## Installation
 
 ### Global Installation (Recommended)
 
@@ -52,43 +53,59 @@ bun run dev
 
 ---
 
-## 🎯 Quick Start
+## Quick Start
+
+### 1. Connect to Azure DevOps
+
+```bash
+# 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](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate).
 
-### 1. Generate Tasks from a Template
+### 2. Generate Tasks from a Template
 
 ```bash
-# Use a preset template
+# Use a preset template (dry-run by default — safe to try)
 atomize generate templates/backend-api.yaml
 
-# Interactive mode
+# When ready to create tasks for real
+atomize generate templates/backend-api.yaml --execute
+
+# Interactive mode (prompts for everything)
 atomize generate
 ```
 
-### 2. Create Your First Template
+### 3. Create Your First Template
 
 ```bash
-# AI-powered creation (free!)
-atomize template create --ai "Backend API with authentication"
-
 # From a preset
 atomize template create --preset backend-api
 
-# Learn from an existing story
-atomize template create --from-story STORY-123
+# 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
 ```
 
-### 3. Validate a Template
+### 4. Validate a Template
 
 ```bash
+# 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
+## Usage Guide
 
 ### Generate Command
 
@@ -104,16 +121,29 @@ atomize generate templates/backend-api.yaml \
   --execute \
   --verbose
 
-# Dry run (preview only)
-atomize generate templates/backend-api.yaml --dry-run
+# Dry run (default — no --execute needed)
+atomize generate templates/backend-api.yaml
+
+# CI/CD mode with JSON report
+atomize generate templates/backend-api.yaml \
+  --execute \
+  --yes \
+  --output report.json
 ```
 
-**Options:**
-- `--platform <type>` - Platform to use (azure-devops, mock)
-- `--execute` - Actually create tasks (default is dry-run)
-- `--dry-run` - Preview without creating tasks
+**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)
+- `-y, --yes` - 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
+
+In non-interactive mode, `--execute` now requires `--yes`. This prevents unattended task creation from wrapper scripts or CI jobs that did not explicitly acknowledge the mutation.
 
 **Example Output:**
 ```
@@ -133,14 +163,13 @@ Summary:
 #### Create a Template
 
 ```bash
-# AI-powered (best for quick starts)
-atomize template create --ai "Create template for React component development"
-
 # From preset (fastest)
 atomize template create --preset frontend-feature
 
-# Learn from story (best for matching your workflow)
-atomize template create --from-story STORY-456 --platform azure-devops
+# Learn from multiple stories (best pattern detection)
+atomize template create \
+  --from-stories STORY-1,STORY-2,STORY-3 \
+  --output my-templates/learned.yaml
 
 # Interactive wizard (most control)
 atomize template create --scratch
@@ -149,7 +178,7 @@ atomize template create --scratch
 #### List Available Presets
 
 ```bash
-atomize template list
+atomize template presets
 ```
 
 **Available Presets:**
@@ -163,13 +192,13 @@ atomize template list
 ```bash
 atomize validate templates/my-template.yaml
 
-# With detailed output
-atomize validate templates/my-template.yaml --verbose
+# Strict mode — warnings become errors (recommended for team/production templates)
+atomize validate templates/my-template.yaml --strict --verbose
 ```
 
 ---
 
-## 🏗️ Template Structure
+## Template Structure
 
 Templates are YAML files that define how to break down user stories into tasks.
 
@@ -200,19 +229,16 @@ tasks:
     description: "Implement business logic and validation"
     estimationPercent: 40
     activity: "Development"
-    tags: ["implementation"]
 
   - title: "Write Tests"
     description: "Unit and integration tests"
     estimationPercent: 30
     activity: "Testing"
-    tags: ["testing"]
 
   - title: "Code Review & Documentation"
     description: "Review and document the implementation"
     estimationPercent: 15
     activity: "Documentation"
-    tags: ["review", "docs"]
 
 # Estimation settings
 estimation:
@@ -229,12 +255,16 @@ validation:
 ### Template Features
 
 #### Variable Interpolation
-Use story data in task titles and descriptions:
-- `${story.title}` - Story title
-- `${story.id}` - Story ID
-- `${story.description}` - Story description
+
+```yaml
+- title: "Design: ${story.title}"
+- description: "Story ${story.id}: ${story.description}"
+```
+
+Available variables: `${story.title}`, `${story.id}`, `${story.description}`, `${story.estimation}`, `${story.tags}`
 
 #### Task Assignment
+
 ```yaml
 assignTo: "@ParentAssignee"  # Inherit from story
 assignTo: "@Me"              # Current user
@@ -242,13 +272,29 @@ assignTo: "user@email.com"   # Specific user
 ```
 
 #### Conditional Tasks
+
 ```yaml
 - title: "Security Review"
   estimationPercent: 10
   condition: '${story.tags} CONTAINS "security"'
 ```
 
+#### Conditional Estimation (v1.1)
+
+Adapt task percentage based on story properties. First matching rule wins; `estimationPercent` is the fallback.
+
+```yaml
+- title: "Implementation"
+  estimationPercent: 50                 # Default
+  estimationPercentCondition:
+    - condition: '${story.tags} CONTAINS "critical"'
+      percent: 60                       # More weight for critical stories
+    - condition: "${story.estimation} >= 13"
+      percent: 55                       # More work for large stories
+```
+
 #### Task Dependencies
+
 ```yaml
 tasks:
   - id: "design"
@@ -258,82 +304,78 @@ tasks:
   - id: "implement"
     title: "Implementation"
     estimationPercent: 60
-    dependsOn: ["design"]  # Must complete design first
+    dependsOn: ["design"]   # Must complete design first
 ```
 
 ---
 
-## 🤖 AI-Powered Template Creation
+## Platform Setup
 
-Atomize supports two free AI providers for template generation:
+### Azure DevOps
 
-### Google Gemini (Cloud - Recommended)
+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
 
-1. Get a free API key: https://makersuite.google.com/app/apikey
-2. Set environment variable:
+2. **Save a connection profile**
    ```bash
-   export GOOGLE_AI_API_KEY="your-key-here"
+   atomize auth add work-ado
+   # Prompts for org URL, project, team, and PAT
    ```
-3. Create templates:
-   ```bash
-   atomize template create --ai "Backend API with OAuth authentication"
-   ```
-
-### Ollama (Local - Complete Privacy)
 
-1. Install Ollama: https://ollama.ai
-2. Download a model:
+3. **Test the connection**
    ```bash
-   ollama pull llama3.2
+   atomize auth test work-ado
    ```
-3. Start the service:
-   ```bash
-   ollama serve
-   ```
-4. Create templates:
+
+4. **Generate tasks**
    ```bash
-   atomize template create --ai-provider ollama --ai "Mobile-first React component"
+   # Use the profile explicitly
+   atomize generate templates/backend-api.yaml --profile work-ado
+
+   # Or set it as default once
+   atomize auth use work-ado
+   atomize generate templates/backend-api.yaml
    ```
 
-### AI Tips
+See `atomize auth --help` for all profile management commands (`list`, `remove`, `rotate`).
 
-- Be specific: "Backend API with JWT auth, rate limiting, and PostgreSQL"
-- Mention your tech stack: "React component with TypeScript and Tailwind CSS"
-- Specify testing requirements: "Include unit tests and E2E tests"
-- Refine iteratively: Use the refine option to adjust the generated template
+### Mock Platform (Testing)
 
----
+```bash
+atomize generate templates/backend-api.yaml --platform mock
+```
 
-## 🔗 Platform Setup
+No configuration required. Includes 7 built-in sample stories.
 
-### 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
+## Strict vs Lenient Validation
 
-2. **Configure Environment Variables**
-   ```bash
-   export AZURE_DEVOPS_ORG_URL="https://dev.azure.com/your-org"
-   export AZURE_DEVOPS_PROJECT="YourProject"
-   export AZURE_DEVOPS_PAT="your-personal-access-token"
-   ```
+Atomize has two validation modes:
 
-3. **Or Use Interactive Setup**
-   ```bash
-   atomize generate templates/backend-api.yaml
-   # CLI will prompt for configuration
-   ```
-
-### Mock Platform (Testing)
+| Mode | Warnings | Best For |
+|------|----------|----------|
+| **Lenient** (default) | Non-blocking | Development, personal templates |
+| **Strict** | Treated as errors | Team templates, CI/CD pipelines |
 
 ```bash
-atomize generate templates/backend-api.yaml --platform mock
+# 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:
+```yaml
+validation:
+  mode: "strict"
 ```
 
 ---
 
-##  Real-World Examples
+## Real-World Examples
 
 ### Example 1: Backend API Feature
 
@@ -349,53 +391,133 @@ atomize generate templates/backend-api.yaml --platform mock
 
 **Total:** 10 story points perfectly distributed
 
-## 🛠️ Advanced Usage
+### Example 2: Multi-Story Learning
 
-### Custom Filters
+```bash
+# Learn from your team's best stories
+atomize template create \
+  --from-stories STORY-100,STORY-115,STORY-132,STORY-148 \
+  --platform azure-devops \
+  --output team-templates/backend-standard.yaml
+
+# Validate the learned template
+atomize validate team-templates/backend-standard.yaml --strict
+
+# Apply it
+atomize generate team-templates/backend-standard.yaml --execute
+```
+
+---
+
+## Advanced Usage
 
-Filter stories with precise criteria:
+### Custom Filters
 
 ```yaml
 filter:
+  team: "Backend Team"                    # Override team (replaces AZURE_DEVOPS_TEAM env var)
   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"]
-  iterations: ["Sprint 23", "Sprint 24"]
-  assignedTo: ["john@company.com", "jane@company.com"]
+  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", "jane@company.com"]
+  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 Strategies
+### Estimation Settings
 
 ```yaml
 estimation:
-  strategy: "percentage"     # Distribute story points by percentage
-  rounding: "nearest"        # nearest, up, down, none
-  minimumTaskPoints: 0.5     # Minimum points per task
+  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
 ```
 
-### Learning from Existing Stories
+### 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:
 
 ```bash
-# Analyze a story and create a template
-atomize template create --from-story STORY-123
+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:
+
+```powershell
+[Environment]::SetEnvironmentVariable("ATOMIZE_PROFILE", "work-ado", "User")
+[Environment]::SetEnvironmentVariable("LOG_LEVEL", "warn", "User")
+```
+
+Or for the current session only:
+
+```powershell
+$env:ATOMIZE_PROFILE = "work-ado"
+$env:LOG_LEVEL       = "warn"
+```
 
-# With percentage normalization
-atomize template create --from-story STORY-123 --normalize
+#### Windows (Command Prompt)
 
-# Keep original percentages
-atomize template create --from-story STORY-123 --no-normalize
+For the current session only:
+
+```cmd
+set ATOMIZE_PROFILE=work-ado
+set LOG_LEVEL=warn
+```
+
+To persist, use **System Properties → Environment Variables** or `setx`:
+
+```cmd
+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:
+
+```bash
+# macOS / Linux
+atomize --env-file ~/.config/atomize.env generate templates/backend-api.yaml
+
+# Windows (PowerShell)
+atomize --env-file $env:USERPROFILE\.config\atomize.env generate templates/backend-api.yaml
 ```
 
+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
+## Testing
 
 ```bash
 # Run all tests
@@ -414,65 +536,38 @@ bun test --watch
 ### Development Setup
 
 ```bash
-# Clone the repository
 git clone https://github.com/Simao-Pereira-Gomes/atomize.git
 cd atomize
-
-# Install dependencies
 bun install
-
-# Run in development mode
 bun run dev
-
-# Run tests
 bun test
-
-# Build
 bun run build
 ```
 
 ---
 
-## 📝 Roadmap
-
-### v0.1.0 - Initial Release ✅
-- [x] Core task generation engine
-- [x] Azure DevOps integration
-- [x] AI-powered template creation
-- [x] Preset templates
-- [x] Story learning
-- [x] Interactive wizards
+## Troubleshooting
 
-### v0.2.0 - Enhanced Features
-- [ ] GitHub Issues integration
-- [ ] Jira integration
-- [ ] VS Code extension
-
-### v0.3.0 - Advanced Capabilities
-- [ ] Multi-story batch processing
-- [ ] Custom estimation formulas
-- [ ] Template inheritance
-- [ ] Workflow automation
-- [ ] Analytics dashboard
-
----
+### "Not authenticated" error
 
-## 🐛 Troubleshooting
+```bash
+# Check what profiles are saved
+atomize auth list
 
-### Common Issues
+# Add a profile if none exist
+atomize auth add work-ado
 
-**"Not authenticated" error**
-```bash
-# Make sure environment variables are set
-echo $AZURE_DEVOPS_PAT
+# Test the profile
+atomize auth test work-ado
 
-# Or use interactive mode
-atomize generate --interactive
+# Use it explicitly
+atomize generate templates/backend-api.yaml --profile work-ado
 ```
 
-**"Template validation failed"**
+### "Template validation failed"
+
 ```bash
-# Check your template
+# Get detailed output
 atomize validate templates/my-template.yaml --verbose
 
 # Common issues:
@@ -481,24 +576,27 @@ atomize validate templates/my-template.yaml --verbose
 # - Missing required fields
 ```
 
-**AI provider not available**
-```bash
-# For Gemini
-export GOOGLE_AI_API_KEY="your-key"
+---
 
-# For Ollama
-ollama serve  # Must be running
-ollama pull llama3.2  # Model must be downloaded
-```
+## Documentation
+
+- [Getting Started](./docs/Getting-Started.md) - First steps and core concepts
+- [CLI Reference](./docs/Cli-Reference.md) - Complete command and flag reference
+- [Template Reference](./docs/Template-Reference.md) - Full template schema
+- [Validation Modes](./docs/Validation-Modes.md) - Strict vs lenient explained
+- [Story Learner](./docs/Story-Learner.md) - Generate templates from existing stories
+- [Common Validation Errors](./docs/Common-Validation-Errors.md) - Fix validation failures
+- [Platform Guide](./docs/Platform-Guide.md) - Azure DevOps setup
+- [Template Wizard Guide](./docs/template-wizard-guide.md) - Interactive wizard walkthrough
 
 ---
 
-## 📄 License
+## License
 
 MIT License - see [LICENSE](LICENSE) file for details
 
-## 📧 Support
+## Support
 
-- 🐛 [Report a Bug](https://github.com/Simao-Pereira-Gomes/atomize/issues)
-- 💡 [Request a Feature](https://github.com/Simao-Pereira-Gomes/atomize/issues)
-- 💬 [Discussions](https://github.com/Simao-Pereira-Gomes/atomize/discussions)
+- [Report a Bug](https://github.com/Simao-Pereira-Gomes/atomize/issues)
+- [Request a Feature](https://github.com/Simao-Pereira-Gomes/atomize/issues)
+- [Discussions](https://github.com/Simao-Pereira-Gomes/atomize/discussions)