@sppg2001/atomize 1.1.0 → 1.2.0

package/examples/README.md

@@ -11,6 +11,7 @@ Real-world Atomize template examples. Each file is a working template you can va
 | [`fullstack.yaml`](#fullstackyaml) | Combined backend + frontend with a branching task graph |
 | [`conditional-dependencies-template.yaml`](#conditional-dependencies-templateyaml) | Conditional tasks — tasks that only appear when a story meets specific criteria |
 | [`conditional-percentage-template.yaml`](#conditional-percentage-templateyaml) | Conditional estimation — task weights that adapt to story size and tags |
+| [`advanced-filtering.yaml`](#advanced-filteringyaml) | Full filter criteria showcase: state exclusion, historical states, area/iteration hierarchy, date filters, team override |
 
 ---
 
@@ -159,6 +160,36 @@ atomize generate examples/conditional-percentage-template.yaml --platform mock -
 
 ---
 
+## advanced-filtering.yaml
+
+A reference template that demonstrates every available filter option. Use it as a starting point when you need precise control over which work items Atomize processes.
+
+**Key features shown:**
+
+| Filter | What it does |
+|--------|-------------|
+| `team` | Overrides the `AZURE_DEVOPS_TEAM` env var 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) |
+| `iterationsUnder` | Matches all sprints under `Release 3` (not just one sprint) |
+| `changedAfter` | Only items touched in the last 14 days (`@Today-14`) |
+| `createdAfter` | Only items created in the last 90 days (`@Today-90`) |
+
+**Supported `@Today` macro syntax:**
+- `@Today` — start of today
+- `@Today-N` — N days in the past (e.g. `@Today-7`)
+- `@Today+N` — N days in the future
+- Also: `@StartOfWeek`, `@StartOfMonth`, `@StartOfYear` (with optional offsets)
+
+**Try it:**
+```bash
+atomize validate examples/advanced-filtering.yaml
+atomize generate examples/advanced-filtering.yaml --platform mock --dry-run
+```
+
+---
+
 ## Running All Examples
 
 ```bash

package/examples/advanced-filtering.yaml

@@ -0,0 +1,113 @@
+version: "1.0"
+name: "Advanced Filtering Demo"
+description: |
+  Demonstrates the full range of filter criteria: state exclusion, historical
+  state matching, area/iteration hierarchy traversal, date-based filters, and
+  team override.
+author: "Atomize"
+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
+  team: "Backend Team"
+
+  workItemTypes:
+    - "User Story"
+
+  # Items currently in these states
+  states:
+    - "Active"
+    - "In Progress"
+
+  # Exclude items in these states (complements `states`)
+  statesExclude:
+    - "Done"
+    - "Removed"
+    - "Won't Fix"
+
+  # Items that passed through code review at some point (historical match)
+  statesWereEver:
+    - "In Review"
+
+  tags:
+    include:
+      - "backend"
+    exclude:
+      - "deprecated"
+      - "on-hold"
+
+  # Match items under "MyProject\Backend" and ALL its sub-areas
+  areaPathsUnder:
+    - "MyProject\\Backend"
+
+  # Match items in the current sprint or any sprint under the current release
+  iterations:
+    - "@CurrentIteration"
+  iterationsUnder:
+    - "MyProject\\Release 3"
+
+  # Only items assigned to the person running the command
+  assignedTo:
+    - "@Me"
+
+  # Only items touched in the last 14 days
+  changedAfter: "@Today-14"
+
+  # Only items created in the last 90 days
+  createdAfter: "@Today-90"
+
+  priority:
+    min: 1
+    max: 2
+
+  excludeIfHasTasks: true
+
+tasks:
+  - id: "design"
+    title: "Design: ${story.title}"
+    description: "Technical design and approach"
+    estimationPercent: 15
+    activity: "Design"
+    assignTo: "@ParentAssignee"
+
+  - id: "implement"
+    title: "Implement: ${story.title}"
+    description: "Core implementation"
+    estimationPercent: 55
+    activity: "Development"
+    assignTo: "@ParentAssignee"
+    dependsOn:
+      - "design"
+
+  - id: "tests"
+    title: "Tests"
+    description: "Unit and integration tests"
+    estimationPercent: 20
+    activity: "Testing"
+    dependsOn:
+      - "implement"
+
+  - id: "review"
+    title: "Code Review & Documentation"
+    estimationPercent: 10
+    activity: "Documentation"
+    dependsOn:
+      - "tests"
+
+estimation:
+  strategy: "percentage"
+  rounding: "nearest"
+  minimumTaskPoints: 0.5
+
+validation:
+  totalEstimationMustBe: 100
+  minTasks: 3
+
+metadata:
+  category: "Demo"
+  difficulty: "beginner"
+  recommendedFor:
+    - "Learning Atomize filter options"
+  estimationGuidelines: "Tasks here are illustrative — adjust percentages to fit your team's workflow."

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sppg2001/atomize",
-	"version": "1.1.0",
+	"version": "1.2.0",
 	"description": "Automatically generate tasks from user stories with smart templates",
 	"type": "module",
 	"main": "./dist/cli/index.js",
@@ -64,7 +64,9 @@
 	"devDependencies": {
 		"@biomejs/biome": "2.3.11",
 		"@types/bun": "1.3.5",
+		"@types/keytar": "^4.4.2",
 		"@types/node": "^25.0.3",
+		"@types/update-notifier": "^6.0.8",
 		"mitata": "^1.0.34"
 	},
 	"peerDependencies": {
@@ -72,12 +74,12 @@
 	},
 	"dependencies": {
 		"@clack/prompts": "^1.1.0",
-		"@google/generative-ai": "^0.24.1",
 		"azure-devops-node-api": "^15.1.2",
 		"chalk": "^5.6.2",
 		"commander": "^14.0.2",
-		"dotenv": "^17.2.3",
+		"keytar": "^7.9.0",
 		"ts-pattern": "^5.9.0",
+		"update-notifier": "^7.3.1",
 		"winston": "^3.19.0",
 		"yaml": "^2.8.2",
 		"zod": "^4.3.5"

package/templates/presets/custom.yaml

@@ -1,6 +1,6 @@
 version: "1.0"
 name: " Custom Example"
-description: "Example template for an Agile project"
+description: "Example template for an Agile project. Handles dev stories, mixed dev+test stories, and test-only stories in a single template using conditional tasks and conditional estimation."
 author: "Atomize"
 tags: []
 
@@ -8,13 +8,13 @@ filter:
   workItemTypes: ["User Story"]
   states: ["Ready for Sprint"]
   tags:
-    include:
-      - "Candidate S117"
+    exclude:
+      - "TestGen"
   excludeIfHasTasks: true
   areaPaths:
     - EA-RSP-Platform\Release 2 Team
   iterations:
-    - EA-RSP-Platform\SOW-7-2026-JAN-MARCH\Sprint 117
+    - "@CurrentIteration"
 
 tasks:
   - title: "Analysis & Playback"
@@ -22,52 +22,55 @@ tasks:
     activity: "Development"
     tags: []
     assignTo: "@ParentAssignee"
-    condition: '${story.tags} NOT CONTAINS "Testing Only"'
+    condition: '${story.tags} NOT CONTAINS "Testing Only" AND ${story.tags} NOT CONTAINS "Test Only"'
 
   - title: "Build"
     estimationPercent: 50
     activity: "Development"
     tags: []
     assignTo: "@ParentAssignee"
-    condition: '${story.tags} NOT CONTAINS "Testing Only"'
+    condition: '${story.tags} NOT CONTAINS "Testing Only" AND ${story.tags} NOT CONTAINS "Test Only"'
 
   - title: "Developer Test"
     estimationPercent: 25
     activity: "Development"
     tags: []
     assignTo: "@ParentAssignee"
-    condition: '${story.tags} NOT CONTAINS "Testing Only"'
+    condition: '${story.tags} NOT CONTAINS "Testing Only" AND ${story.tags} NOT CONTAINS "Test Only"'
 
   - title: "QA Smoke Test"
     estimationPercent: 0
     activity: "Development"
     tags: []
     assignTo: "@ParentAssignee"
-    condition: '${story.tags} NOT CONTAINS "Testing Only"'
+    condition: '${story.tags} NOT CONTAINS "Testing Only" AND ${story.tags} NOT CONTAINS "Test Only"'
 
   - title: "Wiki"
     estimationPercent: 5
     activity: "Development"
     tags: []
     assignTo: "@ParentAssignee"
-    condition: '${story.tags} NOT CONTAINS "Testing Only"'
+    condition: '${story.tags} NOT CONTAINS "Testing Only" AND ${story.tags} NOT CONTAINS "Test Only"'
 
   - title: "Code Review "
     estimationPercent: 0
     activity: "Development"
     tags: []
     assignTo: "@Unassigned"
-    condition: '${story.tags} NOT CONTAINS "Testing Only"'
+    condition: '${story.tags} NOT CONTAINS "Testing Only" AND ${story.tags} NOT CONTAINS "Test Only"'
 
   - title: "Physical Data Model Updated"
     estimationPercent: 0
     activity: "Development"
     tags: []
     assignTo: "@ParentAssignee"
-    condition: '${story.tags} NOT CONTAINS "Testing Only"'
+    condition: '${story.tags} NOT CONTAINS "Testing Only" AND ${story.tags} NOT CONTAINS "Test Only"'
 
   - title: "Test Preparation"
     estimationPercent: 40
+    estimationPercentCondition:
+      - condition: '${story.tags} CONTAINS "Testing Only" OR ${story.tags} CONTAINS "Test Only"'
+        percent: 59.70
     activity: "Testing"
     tags: []
     condition: '${story.tags} NOT CONTAINS "Dev Only"'
@@ -75,6 +78,9 @@ tasks:
 
   - title: "Test Execution"
     estimationPercent: 27
+    estimationPercentCondition:
+      - condition: '${story.tags} CONTAINS "Testing Only" OR ${story.tags} CONTAINS "Test Only"'
+        percent: 40.30
     activity: "Testing"
     tags: []
     condition: '${story.tags} NOT CONTAINS "Dev Only"'
@@ -106,7 +112,7 @@ tasks:
     activity: "Development"
     tags: []
     assignTo: "@ParentAssignee"
-    condition: '${story.tags} NOT CONTAINS "Testing Only"'
+    condition: '${story.tags} NOT CONTAINS "Testing Only" AND ${story.tags} NOT CONTAINS "Test Only"'
 
 estimation:
   strategy: "percentage"
@@ -116,4 +122,9 @@ estimation:
 metadata:
   category: "Agile Project"
   recommendedFor: []
-  estimationGuidelines: "Based on possible Agile project workflow"
+  estimationGuidelines: |
+    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

package/templates/presets/custom-testOnly.yaml

@@ -1,65 +0,0 @@
-version: "1.0"
-name: "Custom Example - Test Only"
-description: "Example template containing only test tasks (percentages normalized to 100)"
-author: "Atomize"
-tags: []
-
-filter:
-  workItemTypes: ["User Story"]
-  states: ["Ready for Sprint"]
-  tags:
-    include:
-      - "Test Only"
-    exclude:
-      - "TestGen"
-  excludeIfHasTasks: false
-  areaPaths:
-    - EA-RSP-Platform\Release 2 Team
-  iterations:
-    - EA-RSP-Platform\SOW-7-2026-JAN-MARCH\Sprint 116
-
-tasks:
-  - title: "Test Preparation"
-    estimationPercent: 59.7014925373
-    activity: "Testing"
-    tags: []
-    condition: '${story.tags} NOT CONTAINS "Dev Only"'
-    assignTo: "@Unassigned"
-
-  - title: "Test Execution"
-    estimationPercent: 40.2985074627
-    activity: "Testing"
-    tags: []
-    condition: '${story.tags} NOT CONTAINS "Dev Only"'
-    assignTo: "@Unassigned"
-
-  - title: "Automation Testing"
-    estimationPercent: 0
-    activity: "Test Automation"
-    tags: []
-    condition: '${story.tags} NOT CONTAINS "Dev Only"'
-    assignTo: "@Unassigned"
-
-  - title: "Test Review"
-    estimationPercent: 0
-    activity: "Testing"
-    tags: []
-    condition: '${story.tags} NOT CONTAINS "Dev Only"'
-    assignTo: "@Unassigned"
-
-  - title: "Release Notes"
-    estimationPercent: 0
-    activity: "Testing"
-    tags: []
-    condition: '${story.tags} NOT CONTAINS "Dev Only"'
-    assignTo: "@Unassigned"
-
-estimation:
-  strategy: "percentage"
-  rounding: "none"
-  minimumTaskPoints: 0
-
-metadata:
-  category: "Agile Project"
-  recommendedFor: []
-  estimationGuidelines: "Test-only workflow; percentages normalized from original template"