@sppg2001/atomize 1.0.3 → 1.2.0

package/examples/README.md

@@ -0,0 +1,215 @@
+# Examples
+
+Real-world Atomize template examples. Each file is a working template you can validate and run immediately.
+
+## Files
+
+| File | What it demonstrates |
+|------|----------------------|
+| [`backend.yaml`](#backendyaml) | Standard backend API workflow with task dependencies |
+| [`frontend.yaml`](#frontendyaml) | React component development workflow |
+| [`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 |
+
+---
+
+## backend.yaml
+
+A production-ready backend API template. Covers the full development cycle from API design through code review, with dependencies enforcing a logical order.
+
+**Matches:** User Stories and Product Backlog Items tagged `backend` or `api`, in states `New`, `Approved`, or `Active`, that don't already have tasks.
+
+**Tasks (6):**
+1. Design API Specification — 10%
+2. Database Schema Changes — 20%
+3. Implement Business Logic — 35% *(depends on design + schema)*
+4. Unit & Integration Tests — 20% *(depends on implementation)*
+5. API Documentation — 5%
+6. Code Review & Refinement — 10%
+
+**Try it:**
+```bash
+atomize validate examples/backend.yaml
+atomize generate examples/backend.yaml --platform mock --dry-run
+```
+
+---
+
+## frontend.yaml
+
+A React component development template covering the full UI lifecycle including accessibility testing.
+
+**Matches:** User Stories tagged `frontend` or `react`, in states `New` or `Approved`, without existing tasks.
+
+**Tasks (6):**
+1. UI/UX Design Review — 10%
+2. Component Structure & Setup — 15%
+3. Component Logic Implementation — 30% *(depends on structure)*
+4. Styling & Responsive Design — 20%
+5. Accessibility Testing — 10%
+6. Component Testing — 15% *(depends on logic)*
+
+**Try it:**
+```bash
+atomize validate examples/frontend.yaml
+atomize generate examples/frontend.yaml --platform mock --dry-run
+```
+
+---
+
+## fullstack.yaml
+
+A combined backend + frontend template for end-to-end features. Uses a branching dependency graph where the backend and frontend tracks run in parallel after the design phase, then converge at integration.
+
+**Matches:** User Stories tagged `fullstack`, in states `New` or `Active`, without existing tasks.
+
+**Tasks (9):**
+1. Technical Design — 10%
+2. Backend API Implementation — 20% *(depends on design)*
+3. Database Implementation — 15% *(conditional: only if story has `database` tag)*
+4. Backend Tests — 10% *(depends on backend API)*
+5. Frontend Components — 20% *(depends on design)*
+6. Styling & Responsive Design — 10%
+7. Frontend Tests — 8% *(depends on frontend components)*
+8. Frontend-Backend Integration — 12% *(depends on both tracks)*
+9. Documentation — 5%
+
+**Try it:**
+```bash
+atomize validate examples/fullstack.yaml
+atomize generate examples/fullstack.yaml --platform mock --dry-run
+```
+
+---
+
+## conditional-dependencies-template.yaml
+
+Demonstrates **conditional tasks** — tasks that are only created when a story meets specific criteria. When a conditional task is skipped, its estimation is redistributed to the remaining tasks.
+
+**Matches:** User Stories tagged `development`.
+
+**Key features shown:**
+- `condition` field with tag-based rules (`CONTAINS "backend"`, `CONTAINS "frontend"`, `CONTAINS "security"`)
+- `condition` with compound logic (`AND`, `OR`, `NOT CONTAINS`)
+- `condition` based on numeric fields (`${story.estimation} >= 13`)
+- Dependencies that span conditional tasks (e.g., `unit-tests` depends on `backend-api` and `frontend-ui` — whichever were created)
+
+**Tasks (9, most conditional):**
+
+| Task | Created when |
+|------|-------------|
+| UI/UX Design | Always |
+| Backend API | Story has `backend` tag |
+| Frontend UI | Story has `frontend` tag |
+| Accessibility Testing | Story has `frontend` tag OR doesn't have `legacy` tag |
+| Security Review | Story has `security` tag AND priority ≤ 2 |
+| Unit Tests | Always *(depends on whichever of backend/frontend exist)* |
+| Integration Tests | Always *(depends on unit tests)* |
+| Performance Testing | Story estimation ≥ 13 points |
+| Documentation | Always *(depends on unit tests)* |
+| Deployment | Always *(depends on integration tests + docs)* |
+
+**Try it:**
+```bash
+atomize validate examples/conditional-dependencies-template.yaml
+atomize generate examples/conditional-dependencies-template.yaml --platform mock --dry-run
+```
+
+---
+
+## conditional-percentage-template.yaml
+
+Demonstrates **`estimationPercentCondition`** — each task's percentage of the story adapts based on the story's size and tags. This is useful when the same task represents different amounts of work depending on story complexity.
+
+**Matches:** All User Stories without existing tasks.
+
+**Key features shown:**
+- `estimationPercentCondition` on multiple tasks
+- First-match-wins rule evaluation order
+- Conditional task combined with conditional estimation (the `frontend-impl` task is both conditional *and* has an adaptive percentage)
+- Normalization using resolved conditional percentages as the baseline (not static fallbacks)
+
+**Tasks (5):**
+
+| Task | Default % | Conditional rules |
+|------|-----------|-------------------|
+| Technical Design | 10% | ≥ 13 pts → 20%, ≥ 5 pts → 15% |
+| Backend Implementation | 60% | `fullstack` tag → 40%, ≥ 5 pts → 50% |
+| Frontend Implementation | 30% | `complex-ui` tag → 40% — *only created for `fullstack` stories* |
+| Testing & QA | 20% | `critical` + ≥ 8 pts → 30%, `critical` alone → 25% |
+| Code Review | 5% | Always 5% |
+
+**Scenarios and their resolved splits (before normalization):**
+
+| Scenario | Design | Backend | Frontend | Testing | Review | Total |
+|----------|--------|---------|----------|---------|--------|-------|
+| Small backend (< 5 pts) | 10% | 60% | — | 20% | 5% | 95% |
+| Medium backend (5–12 pts) | 15% | 50% | — | 20% | 5% | 90% |
+| Medium fullstack (5–12 pts) | 15% | 40% | 30% | 20% | 5% | 110% |
+| Large critical fullstack (≥ 13 pts, `critical`) | 20% | 40% | 30% | 30% | 5% | 125% |
+
+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
+```
+
+---
+
+## 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
+# Validate all examples
+for f in examples/*.yaml; do
+  echo "Validating $f..."
+  atomize validate "$f"
+done
+
+# Test all examples against mock data
+for f in examples/*.yaml; do
+  echo "Testing $f..."
+  atomize generate "$f" --platform mock --dry-run
+done
+```
+
+---
+
+## See Also
+
+- [Template Reference](../docs/Template-Reference.md) — full template schema
+- [Validation Modes](../docs/Validation-Modes.md) — strict vs lenient validation
+- [CLI Reference](../docs/Cli-Reference.md) — all commands and flags

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/examples/conditional-percentage-template.yaml

@@ -0,0 +1,139 @@
+version: "1.0"
+name: "Story-Aware Task Allocation"
+description: >
+  Demonstrates estimationPercentCondition — each task's weight adapts to
+  the story's size and tags. When the conditional frontend-impl task is
+  skipped, the remaining tasks carry their already-resolved conditional
+  percents into normalization, so the final split is always accurate.
+author: "Atomize"
+tags: ["demo", "conditional-percent", "adaptive"]
+
+filter:
+  workItemTypes:
+    - "User Story"
+  excludeIfHasTasks: true
+
+estimation:
+  strategy: "percentage"
+  rounding: "nearest"
+  minimumTaskPoints: 0.5
+
+tasks:
+  # ── Design ────────────────────────────────────────────────────────────────
+  # Allocation scales with story size.
+  # Small stories (< 5 pts):  10 %  — quick design, no surprises expected
+  # Medium stories (5–12 pts): 15 %  — moderate up-front work
+  # Large stories (≥ 13 pts):  20 %  — epic-scale requires thorough design
+  - id: "design"
+    title: "Technical Design & Architecture"
+    description: "Define architecture, API contracts, and data models for ${story.title}"
+    activity: "Design"
+    assignTo: "@ParentAssignee"
+    estimationPercent: 10
+    estimationPercentCondition:
+      - condition: "${story.estimation} >= 13"
+        percent: 20
+      - condition: "${story.estimation} >= 5"
+        percent: 15
+    tags: ["design"]
+
+  # ── Backend implementation ─────────────────────────────────────────────────
+  # Rules evaluated in order — first match wins.
+  #
+  # • fullstack tag present  → 40 %  (budget shared with the frontend task)
+  # • medium/large story     → 50 %  (more surface area to cover carefully)
+  # • fallback               → 60 %  (small, pure-backend story)
+  - id: "backend-impl"
+    title: "Backend Implementation"
+    description: "Implement API endpoints and business logic for ${story.title}"
+    activity: "Development"
+    assignTo: "@ParentAssignee"
+    dependsOn: ["design"]
+    estimationPercent: 60
+    estimationPercentCondition:
+      - condition: '${story.tags} CONTAINS "fullstack"'
+        percent: 40
+      - condition: "${story.estimation} >= 5"
+        percent: 50
+    tags: ["backend"]
+
+  # ── Frontend implementation (conditional task) ─────────────────────────────
+  # Only created when the story is tagged "fullstack".
+  # When this task is SKIPPED, the remaining tasks' resolved conditional
+  # percents are used as the baseline for normalization — so Design and
+  # Backend get accurate relative weights rather than stale static values.
+  #
+  # complex-ui tag → extra allocation for non-trivial UIs
+  - id: "frontend-impl"
+    title: "Frontend Implementation"
+    description: "Build UI components and integrate with the API for ${story.title}"
+    activity: "Development"
+    assignTo: "@ParentAssignee"
+    dependsOn: ["design"]
+    condition: '${story.tags} CONTAINS "fullstack"'
+    estimationPercent: 30
+    estimationPercentCondition:
+      - condition: '${story.tags} CONTAINS "complex-ui"'
+        percent: 40
+    tags: ["frontend"]
+
+  # ── Testing & QA ──────────────────────────────────────────────────────────
+  # Critical stories need more thorough test coverage.
+  # AND-condition is checked first: critical + large ≥ 8 pts → 30 %
+  # If only critical (smaller story)                        → 25 %
+  # Otherwise                                               → 20 %
+  - id: "testing"
+    title: "Testing & QA"
+    description: "Write automated tests and perform QA for ${story.title}"
+    activity: "Testing"
+    assignTo: "@ParentAssignee"
+    dependsOn: ["backend-impl"]
+    estimationPercent: 20
+    estimationPercentCondition:
+      - condition: '${story.tags} CONTAINS "critical" AND ${story.estimation} >= 8'
+        percent: 30
+      - condition: '${story.tags} CONTAINS "critical"'
+        percent: 25
+    tags: ["testing"]
+
+  # ── Code review ────────────────────────────────────────────────────────────
+  # Always 5 % — lightweight overhead regardless of story size or tags.
+  # No estimationPercentCondition needed here.
+  - id: "code-review"
+    title: "Code Review & Documentation"
+    description: "Peer review and document all changes for ${story.title}"
+    activity: "Documentation"
+    assignTo: "@ParentAssignee"
+    dependsOn: ["testing"]
+    estimationPercent: 5
+    tags: ["review", "documentation"]
+
+# ── Metadata ─────────────────────────────────────────────────────────────────
+metadata:
+  category: "Demo"
+  difficulty: "intermediate"
+  recommendedFor:
+    - "Demonstrating estimationPercentCondition"
+    - "Adaptive task weighting by story size or tags"
+  estimationGuidelines: |
+    Effective resolved percentages by scenario (before normalization):
+
+    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):
+      design=15  backend=50  testing=20  review=5  → total=90 → normalised to 100
+    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"):
+      design=15  backend=50  testing=25  review=5  → total=95 → normalised to 100
+
+    Key behaviour: when frontend-impl is skipped (no "fullstack" tag) the
+    remaining tasks already hold their *resolved* conditional percents before
+    normalization runs, so the final ratio reflects the per-story adjustments
+    rather than the static fallback values.
+  examples:
+    - "Small pure-backend story (2 pts, tags: [backend])"
+    - "Medium fullstack story (8 pts, tags: [fullstack])"
+    - "Large critical fullstack story (13 pts, tags: [fullstack, critical, complex-ui])"

package/examples/fullstack.yaml

@@ -15,11 +15,6 @@ filter:
       - "fullstack"
   excludeIfHasTasks: true
 
-# Variables for conditionals
-variables:
-  hasDatabase: true
-  hasAuth: false
-
 tasks:
   # Design Phase
   - id: "design-overview"
@@ -59,7 +54,7 @@ tasks:
     estimationPercent: 15
     tags: ["database", "backend"]
     activity: "Development"
-    condition: "${variables.hasDatabase}"
+    condition: '${story.tags} CONTAINS "database"'
 
   - id: "backend-tests"
     title: "Backend Tests"

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sppg2001/atomize",
-	"version": "1.0.3",
+	"version": "1.2.0",
 	"description": "Automatically generate tasks from user stories with smart templates",
 	"type": "module",
 	"main": "./dist/cli/index.js",
@@ -21,7 +21,7 @@
 		"examples"
 	],
 	"scripts": {
-		"dev": "bun run src/cli/index.ts",
+		"dev": "ATOMIZE_DEV=true bun run src/cli/index.ts",
 		"build": "bun run typecheck && bun run build:bun",
 		"postbuild": "node make-executable.js",
 		"build:bun": "bun build ./src/cli/index.ts --outdir ./dist/cli --target node --format esm",
@@ -37,7 +37,8 @@
 		"validate:package": "test -d dist && test -f dist/cli/index.js && test -d templates/presets",
 		"check": "bun typecheck && bun test",
 		"lint": "bunx biome check --max-diagnostics 100",
-		"lint:fix": "bunx biome check --fix --max-diagnostics 100"
+		"lint:fix": "bunx biome check --fix --max-diagnostics 100",
+		"benchmark": "bun run benchmarks/index.ts"
 	},
 	"keywords": [
 		"devops",
@@ -63,20 +64,22 @@
 	"devDependencies": {
 		"@biomejs/biome": "2.3.11",
 		"@types/bun": "1.3.5",
-		"@types/inquirer": "^9.0.9",
-		"@types/node": "^25.0.3"
+		"@types/keytar": "^4.4.2",
+		"@types/node": "^25.0.3",
+		"@types/update-notifier": "^6.0.8",
+		"mitata": "^1.0.34"
 	},
 	"peerDependencies": {
 		"typescript": "^5.9.3"
 	},
 	"dependencies": {
-		"@google/generative-ai": "^0.24.1",
+		"@clack/prompts": "^1.1.0",
 		"azure-devops-node-api": "^15.1.2",
 		"chalk": "^5.6.2",
 		"commander": "^14.0.2",
-		"dotenv": "^17.2.3",
-		"inquirer": "^13.1.0",
+		"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"