@sppg2001/atomize 1.2.4 → 2.0.0

package/examples/README.md

@@ -1,6 +1,6 @@
 # Examples
 
-Real-world Atomize template examples. Each file is a working template you can validate and run immediately.
+Real-world Atomize template examples. Each file is a working template you can validate immediately and dry-run against either matching work items or explicit mock stories.
 
 ## Files
 
@@ -32,7 +32,7 @@ A production-ready backend API template. Covers the full development cycle from
 **Try it:**
 ```bash
 atomize validate examples/backend.yaml
-atomize generate examples/backend.yaml --platform mock --dry-run
+atomize generate examples/backend.yaml --platform mock
 ```
 
 ---
@@ -54,7 +54,7 @@ A React component development template covering the full UI lifecycle including
 **Try it:**
 ```bash
 atomize validate examples/frontend.yaml
-atomize generate examples/frontend.yaml --platform mock --dry-run
+atomize generate examples/frontend.yaml --platform mock
 ```
 
 ---
@@ -79,7 +79,7 @@ A combined backend + frontend template for end-to-end features. Uses a branching
 **Try it:**
 ```bash
 atomize validate examples/fullstack.yaml
-atomize generate examples/fullstack.yaml --platform mock --dry-run
+atomize generate examples/fullstack.yaml --platform mock --story STORY-004
 ```
 
 ---
@@ -114,7 +114,7 @@ Demonstrates **conditional tasks** — tasks that are only created when a story
 **Try it:**
 ```bash
 atomize validate examples/conditional-dependencies-template.yaml
-atomize generate examples/conditional-dependencies-template.yaml --platform mock --dry-run
+atomize generate examples/conditional-dependencies-template.yaml --platform mock --story STORY-004
 ```
 
 ---
@@ -155,7 +155,7 @@ All totals are normalized to exactly 100% at generation time.
 **Try it:**
 ```bash
 atomize validate examples/conditional-percentage-template.yaml
-atomize generate examples/conditional-percentage-template.yaml --platform mock --dry-run
+atomize generate examples/conditional-percentage-template.yaml --platform mock
 ```
 
 ---
@@ -168,7 +168,7 @@ A reference template that demonstrates every available filter option. Use it as
 
 | Filter | What it does |
 |--------|-------------|
-| `team` | Overrides the `AZURE_DEVOPS_TEAM` env var for this template |
+| `team` | Overrides the team from the selected Azure DevOps profile for this template |
 | `statesExclude` | Excludes items in `Done`, `Removed`, or `Won't Fix` |
 | `statesWereEver` | Matches items that passed through `In Review` historically |
 | `areaPathsUnder` | Matches `MyProject\Backend` **and all sub-areas** (hierarchy traversal) |
@@ -185,7 +185,7 @@ A reference template that demonstrates every available filter option. Use it as
 **Try it:**
 ```bash
 atomize validate examples/advanced-filtering.yaml
-atomize generate examples/advanced-filtering.yaml --platform mock --dry-run
+atomize generate examples/advanced-filtering.yaml --platform mock --story STORY-001
 ```
 
 ---
@@ -199,11 +199,16 @@ for f in examples/*.yaml; do
   atomize validate "$f"
 done
 
-# Test all examples against mock data
-for f in examples/*.yaml; do
+# Dry-run examples that match the bundled mock filters
+for f in examples/backend.yaml examples/frontend.yaml examples/conditional-percentage-template.yaml; do
   echo "Testing $f..."
-  atomize generate "$f" --platform mock --dry-run
+  atomize generate "$f" --platform mock
 done
+
+# Dry-run examples whose filters are intentionally more specific than the mock dataset
+atomize generate examples/fullstack.yaml --platform mock --story STORY-004
+atomize generate examples/conditional-dependencies-template.yaml --platform mock --story STORY-004
+atomize generate examples/advanced-filtering.yaml --platform mock --story STORY-001
 ```
 
 ---

package/examples/advanced-filtering.yaml

@@ -10,7 +10,7 @@ tags: ["demo", "filtering", "advanced"]
 # Each option below is independent — in a real template you would only use
 # the subset that makes sense for your workflow.
 filter:
-  # Override the team configured in AZURE_DEVOPS_TEAM env var
+  # Override the team from the selected Azure DevOps profile
   team: "Backend Team"
 
   workItemTypes:

package/examples/conditional-dependencies-template.yaml

@@ -31,7 +31,10 @@ tasks:
     estimationPercent: 30
     activity: "Development"
     dependsOn: ["design"]
-    condition: '${story.tags} CONTAINS "backend"'
+    condition:
+      field: tags
+      operator: contains
+      value: backend
     tags:
       - "backend"
       - "api"
@@ -43,7 +46,10 @@ tasks:
     estimationPercent: 35
     activity: "Development"
     dependsOn: ["design"]
-    condition: '${story.tags} CONTAINS "frontend"'
+    condition:
+      field: tags
+      operator: contains
+      value: frontend
     tags:
       - "frontend"
 
@@ -54,7 +60,14 @@ tasks:
     estimationPercent: 7
     activity: "Testing"
     dependsOn: ["frontend-ui"]
-    condition: '${story.tags} CONTAINS "frontend" OR ${story.tags} NOT CONTAINS "legacy"'
+    condition:
+      any:
+        - field: tags
+          operator: contains
+          value: frontend
+        - field: tags
+          operator: not-contains
+          value: legacy
     tags:
       - "accessibility"
       - "testing"
@@ -66,7 +79,14 @@ tasks:
     estimationPercent: 8
     activity: "Testing"
     dependsOn: ["backend-api", "frontend-ui"]
-    condition: '${story.tags} CONTAINS "security" AND ${story.priority} <= 2'
+    condition:
+      all:
+        - field: tags
+          operator: contains
+          value: security
+        - field: priority
+          operator: lte
+          value: 2
     priority: 1
     tags:
       - "security"
@@ -97,7 +117,10 @@ tasks:
     estimationPercent: 10
     activity: "Testing"
     dependsOn: ["integration-tests"]
-    condition: '${story.estimation} >= 13'
+    condition:
+      field: estimation
+      operator: gte
+      value: 13
     tags:
       - "performance"
 

package/examples/conditional-percentage-template.yaml

@@ -31,9 +31,15 @@ tasks:
     assignTo: "@ParentAssignee"
     estimationPercent: 10
     estimationPercentCondition:
-      - condition: "${story.estimation} >= 13"
+      - condition:
+          field: estimation
+          operator: gte
+          value: 13
         percent: 20
-      - condition: "${story.estimation} >= 5"
+      - condition:
+          field: estimation
+          operator: gte
+          value: 5
         percent: 15
     tags: ["design"]
 
@@ -51,9 +57,15 @@ tasks:
     dependsOn: ["design"]
     estimationPercent: 60
     estimationPercentCondition:
-      - condition: '${story.tags} CONTAINS "fullstack"'
+      - condition:
+          field: tags
+          operator: contains
+          value: fullstack
         percent: 40
-      - condition: "${story.estimation} >= 5"
+      - condition:
+          field: estimation
+          operator: gte
+          value: 5
         percent: 50
     tags: ["backend"]
 
@@ -70,10 +82,16 @@ tasks:
     activity: "Development"
     assignTo: "@ParentAssignee"
     dependsOn: ["design"]
-    condition: '${story.tags} CONTAINS "fullstack"'
+    condition:
+      field: tags
+      operator: contains
+      value: fullstack
     estimationPercent: 30
     estimationPercentCondition:
-      - condition: '${story.tags} CONTAINS "complex-ui"'
+      - condition:
+          field: tags
+          operator: contains
+          value: complex-ui
         percent: 40
     tags: ["frontend"]
 
@@ -90,9 +108,19 @@ tasks:
     dependsOn: ["backend-impl"]
     estimationPercent: 20
     estimationPercentCondition:
-      - condition: '${story.tags} CONTAINS "critical" AND ${story.estimation} >= 8'
+      - condition:
+          all:
+            - field: tags
+              operator: contains
+              value: critical
+            - field: estimation
+              operator: gte
+              value: 8
         percent: 30
-      - condition: '${story.tags} CONTAINS "critical"'
+      - condition:
+          field: tags
+          operator: contains
+          value: critical
         percent: 25
     tags: ["testing"]
 
@@ -120,13 +148,13 @@ metadata:
 
     Scenario A — small backend-only story (< 5 pts, no "fullstack" tag):
       design=10  backend=60  testing=20  review=5  → total=95 → normalised to 100
-    Scenario B — medium backend-only story (5–12 pts):
+    Scenario B — medium backend-only story (5/12 pts):
       design=15  backend=50  testing=20  review=5  → total=90 → normalised to 100
-    Scenario C — medium fullstack story (5–12 pts, "fullstack" tag):
+    Scenario C — medium fullstack story (5/12 pts, "fullstack" tag):
       design=15  backend=40  frontend=30  testing=20  review=5  → total=110 → normalised
     Scenario D — large critical fullstack story (≥ 13 pts, "critical" + "fullstack" tags):
       design=20  backend=40  frontend=30  testing=30  review=5  → total=125 → normalised
-    Scenario E — medium critical backend-only story (5–12 pts, "critical", no "fullstack"):
+    Scenario E — medium critical backend-only story (5/12 pts, "critical", no "fullstack"):
       design=15  backend=50  testing=25  review=5  → total=95 → normalised to 100
 
     Key behaviour: when frontend-impl is skipped (no "fullstack" tag) the

package/examples/fullstack.yaml

@@ -54,7 +54,10 @@ tasks:
     estimationPercent: 15
     tags: ["database", "backend"]
     activity: "Development"
-    condition: '${story.tags} CONTAINS "database"'
+    condition:
+      field: tags
+      operator: contains
+      value: database
 
   - id: "backend-tests"
     title: "Backend Tests"

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sppg2001/atomize",
-	"version": "1.2.4",
+	"version": "2.0.0",
 	"description": "Automatically generate tasks from user stories with smart templates",
 	"type": "module",
 	"main": "./dist/cli/index.js",
@@ -14,7 +14,9 @@
 	},
 	"files": [
 		"dist",
-		"templates/presets",
+		"templates/templates",
+		"templates/mixins",
+		"docs",
 		"README.md",
 		"LICENSE",
 		".env.example",
@@ -33,6 +35,7 @@
 		"test:watch": "bun test --watch",
 		"test:coverage": "bun test --coverage --coverage-reporter=lcov",
 		"typecheck": "tsc --noEmit",
+		"audit": "bun audit --audit-level=moderate",
 		"validate": "bun run src/cli/index.ts validate",
 		"validate:package": "node ./scripts/validate-package.mjs",
 		"check": "bun typecheck && bun test",
@@ -62,27 +65,33 @@
 	"author": "Simão Pereira Gomes",
 	"license": "MIT",
 	"devDependencies": {
-		"@biomejs/biome": "2.3.11",
-		"@types/bun": "1.3.5",
+		"@biomejs/biome": "2.4.12",
+		"@types/bun": "1.3.13",
 		"@types/keytar": "^4.4.2",
-		"@types/node": "^25.0.3",
-		"@types/update-notifier": "^6.0.8",
-		"mitata": "^1.0.34"
+		"@types/node": "^25.6.0",
+		"@types/semver": "^7.7.1",
+		"bun-types": "^1.3.13",
+		"mitata": "^1.0.34",
+		"typescript": "^6.0.3"
 	},
 	"peerDependencies": {
-		"typescript": "^5.9.3"
+		"typescript": "^6.0.3"
 	},
 	"dependencies": {
-		"@clack/prompts": "^1.1.0",
+		"@clack/prompts": "^1.2.0",
 		"azure-devops-node-api": "^15.1.2",
 		"chalk": "^5.6.2",
-		"commander": "^14.0.2",
+		"commander": "^14.0.3",
 		"keytar": "^7.9.0",
+		"openai": "^6.34.0",
+		"semver": "^7.7.4",
 		"ts-pattern": "^5.9.0",
-		"update-notifier": "^7.3.1",
-		"winston": "^3.19.0",
-		"yaml": "^2.8.2",
-		"zod": "^4.3.5"
+		"yaml": "^2.8.3",
+		"zod": "^4.3.6"
+	},
+	"overrides": {
+		"qs": "6.15.1",
+		"underscore": "1.13.8"
 	},
 	"engines": {
 		"node": ">=18.0.0"

package/templates/mixins/docs.yaml

@@ -0,0 +1,16 @@
+name: "Documentation Mixin"
+description: "Standard documentation tasks. Mix into any template to ensure docs are part of the definition of done."
+tasks:
+  - id: "update-docs"
+    title: "Update Documentation: ${story.title}"
+    description: "Update or create user-facing documentation, API docs, and README files to reflect the changes."
+    estimationPercent: 10
+    activity: "Documentation"
+    assignTo: "@Unassigned"
+
+  - id: "changelog-entry"
+    title: "Add Changelog Entry: ${story.title}"
+    description: "Add a clear, user-focused entry to the project changelog describing what changed and why."
+    estimationPercent: 5
+    activity: "Documentation"
+    assignTo: "@ParentAssignee"

package/templates/mixins/security.yaml

@@ -0,0 +1,16 @@
+name: "Security Mixin"
+description: "Common security review tasks. Mix into any feature template to enforce a security gate."
+tasks:
+  - id: "security-review"
+    title: "Security Review: ${story.title}"
+    description: "Review the implementation for security vulnerabilities (OWASP Top 10, input validation, auth/authz, secrets handling)."
+    estimationPercent: 10
+    activity: "Design"
+    assignTo: "@Unassigned"
+
+  - id: "dependency-audit"
+    title: "Dependency Audit: ${story.title}"
+    description: "Audit third-party dependencies for known vulnerabilities (e.g. npm audit, OWASP Dependency-Check)."
+    estimationPercent: 5
+    activity: "Development"
+    assignTo: "@Unassigned"

package/templates/mixins/testing.yaml

@@ -0,0 +1,27 @@
+name: "Testing Mixin"
+description: "Expanded testing tasks. Mix into any template to enforce unit, integration, and E2E test coverage."
+tasks:
+  - id: "unit-tests"
+    title: "Unit Tests: ${story.title}"
+    description: "Write unit tests covering the core logic and edge cases. Aim for ≥80% coverage on changed code."
+    estimationPercent: 15
+    activity: "Testing"
+    assignTo: "@ParentAssignee"
+
+  - id: "integration-tests"
+    title: "Integration Tests: ${story.title}"
+    description: "Write integration tests covering interactions between components, APIs, and external dependencies."
+    estimationPercent: 10
+    activity: "Testing"
+    dependsOn: ["unit-tests"]
+
+  - id: "e2e-tests"
+    title: "End-to-End Tests: ${story.title}"
+    description: "Validate the full user journey through the feature using E2E test scenarios."
+    estimationPercent: 10
+    activity: "Testing"
+    assignTo: "@Unassigned"
+    condition:
+      field: "tags"
+      operator: "contains"
+      value: "e2e"

package/templates/templates/bug.yaml

@@ -0,0 +1,54 @@
+version: "1.0"
+name: "Bug Template"
+description: "Foundation for bug-fix templates. Extend this to inherit a standard investigation and fix task set."
+author: "Atomize"
+tags: ["template", "bug"]
+
+filter:
+  workItemTypes: ["Bug"]
+  states: ["New", "Active", "Committed"]
+  excludeIfHasTasks: true
+
+tasks:
+  - id: "investigate"
+    title: "Investigate: ${story.title}"
+    description: "Reproduce the bug, identify the root cause, and document findings."
+    estimationPercent: 30
+    activity: "Requirements"
+    assignTo: "@ParentAssignee"
+    estimationPercentCondition:
+      - condition:
+          field: "Priority"
+          operator: "lte"
+          value: 2
+        percent: 40
+
+  - id: "fix"
+    title: "Fix: ${story.title}"
+    description: "Implement the fix for the identified root cause."
+    estimationPercent: 40
+    activity: "Development"
+    assignTo: "@ParentAssignee"
+    dependsOn: ["investigate"]
+
+  - id: "verify"
+    title: "Verify Fix: ${story.title}"
+    description: "Verify the fix resolves the issue and does not introduce regressions."
+    estimationPercent: 20
+    activity: "Testing"
+    dependsOn: ["fix"]
+
+  - id: "close"
+    title: "Close & Document: ${story.title}"
+    description: "Update documentation, close the bug, and notify stakeholders."
+    estimationPercent: 10
+    activity: "Documentation"
+    dependsOn: ["verify"]
+
+estimation:
+  strategy: "percentage"
+  rounding: "none"
+  ifParentHasNoEstimation: "warn"
+
+validation:
+  totalEstimationMustBe: 100

package/templates/templates/custom-saved-query.yaml

@@ -0,0 +1,214 @@
+version: "1.0"
+name: "Custom Example — Saved Query"
+description: "Same task breakdown as the custom example, but work item selection is delegated to an existing Azure DevOps saved query instead of a structured filter. Useful when your team already maintains a query that encodes complex area path, iteration, and tag logic."
+author: "Atomize"
+tags: []
+
+filter:
+  savedQuery:
+    path: "Shared Queries/Teams/Platform/Ready for Sprint"
+  excludeIfHasTasks: true
+
+tasks:
+  - title: "Analysis & Playback"
+    estimationPercent: 20
+    activity: "Development"
+    tags: []
+    assignTo: "@ParentAssignee"
+    condition:
+      all:
+        - field: tags
+          operator: not-contains
+          value: Testing Only
+        - field: tags
+          operator: not-contains
+          value: Test Only
+
+  - title: "Build"
+    estimationPercent: 50
+    activity: "Development"
+    tags: []
+    assignTo: "@ParentAssignee"
+    condition:
+      all:
+        - field: tags
+          operator: not-contains
+          value: Testing Only
+        - field: tags
+          operator: not-contains
+          value: Test Only
+
+  - title: "Developer Test"
+    estimationPercent: 25
+    activity: "Development"
+    tags: []
+    assignTo: "@ParentAssignee"
+    condition:
+      all:
+        - field: tags
+          operator: not-contains
+          value: Testing Only
+        - field: tags
+          operator: not-contains
+          value: Test Only
+
+  - title: "QA Smoke Test"
+    estimationPercent: 0
+    activity: "Development"
+    tags: []
+    assignTo: "@ParentAssignee"
+    condition:
+      all:
+        - field: tags
+          operator: not-contains
+          value: Testing Only
+        - field: tags
+          operator: not-contains
+          value: Test Only
+
+  - title: "Wiki"
+    estimationPercent: 5
+    activity: "Development"
+    tags: []
+    assignTo: "@ParentAssignee"
+    condition:
+      all:
+        - field: tags
+          operator: not-contains
+          value: Testing Only
+        - field: tags
+          operator: not-contains
+          value: Test Only
+
+  - title: "Code Review"
+    estimationPercent: 0
+    activity: "Development"
+    tags: []
+    assignTo: "@Unassigned"
+    condition:
+      all:
+        - field: tags
+          operator: not-contains
+          value: Testing Only
+        - field: tags
+          operator: not-contains
+          value: Test Only
+
+  - title: "Physical Data Model Updated"
+    estimationPercent: 0
+    activity: "Development"
+    tags: []
+    assignTo: "@ParentAssignee"
+    condition:
+      all:
+        - field: tags
+          operator: not-contains
+          value: Testing Only
+        - field: tags
+          operator: not-contains
+          value: Test Only
+
+  - title: "Test Preparation"
+    estimationPercent: 40
+    estimationPercentCondition:
+      - condition:
+          any:
+            - field: tags
+              operator: contains
+              value: Testing Only
+            - field: tags
+              operator: contains
+              value: Test Only
+        percent: 59.70
+    activity: "Testing"
+    tags: []
+    condition:
+      field: tags
+      operator: not-contains
+      value: Dev Only
+    assignTo: "@Unassigned"
+
+  - title: "Test Execution"
+    estimationPercent: 27
+    estimationPercentCondition:
+      - condition:
+          any:
+            - field: tags
+              operator: contains
+              value: Testing Only
+            - field: tags
+              operator: contains
+              value: Test Only
+        percent: 40.30
+    activity: "Testing"
+    tags: []
+    condition:
+      field: tags
+      operator: not-contains
+      value: Dev Only
+    assignTo: "@Unassigned"
+
+  - title: "Automation Testing"
+    estimationPercent: 0
+    activity: "Test Automation"
+    tags: []
+    condition:
+      field: tags
+      operator: not-contains
+      value: Dev Only
+    assignTo: "@Unassigned"
+
+  - title: "Test Review"
+    estimationPercent: 0
+    activity: "Testing"
+    tags: []
+    condition:
+      field: tags
+      operator: not-contains
+      value: Dev Only
+    assignTo: "@Unassigned"
+
+  - title: "Release Notes"
+    estimationPercent: 0
+    activity: "Testing"
+    tags: []
+    condition:
+      field: tags
+      operator: not-contains
+      value: Dev Only
+    assignTo: "@Unassigned"
+
+  - title: "Merge to Stable"
+    estimationPercent: 10
+    activity: "Development"
+    tags: []
+    assignTo: "@ParentAssignee"
+    condition:
+      all:
+        - field: tags
+          operator: not-contains
+          value: Testing Only
+        - field: tags
+          operator: not-contains
+          value: Test Only
+
+estimation:
+  strategy: "percentage"
+  rounding: "none"
+  minimumTaskPoints: 0
+
+metadata:
+  category: "Agile Project"
+  recommendedFor: []
+  estimationGuidelines: |
+    Identical task breakdown to the structured-filter custom example.
+    The only difference is in the filter: work item selection is handled
+    entirely by the saved query at the configured path. The query should
+    already encode area path, iteration, and tag constraints so this
+    template stays clean. Update the savedQuery path to match your project.
+
+    Handles three story archetypes in one template:
+    - Dev and Test story (no special tag): dev tasks + test tasks, base percentages apply.
+    - Testing Only / Test Only story: dev tasks skipped; Test Preparation gets 59.70%
+      and Test Execution gets 40.30%.
+    - Dev Only story: test tasks skipped.