@sppg2001/atomize 2.0.0 → 3.0.0

package/examples/README.md

@@ -1,220 +0,0 @@
-# Examples
-
-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
-
-| 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
-```
-
----
-
-## 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
-```
-
----
-
-## 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 --story STORY-004
-```
-
----
-
-## 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 --story STORY-004
-```
-
----
-
-## 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
-```
-
----
-
-## 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 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) |
-| `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 --story STORY-001
-```
-
----
-
-## Running All Examples
-
-```bash
-# Validate all examples
-for f in examples/*.yaml; do
-  echo "Validating $f..."
-  atomize validate "$f"
-done
-
-# 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
-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
-```
-
----
-
-## 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

@@ -1,113 +0,0 @@
-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 from the selected Azure DevOps profile
-  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/backend.yaml

@@ -1,124 +0,0 @@
-version: "1.0"
-name: "Backend API Feature"
-description: "Standard tasks for backend API development"
-author: "Atomize"
-tags: ["backend", "api", "standard"]
-
-# Filter to identify applicable User Stories
-filter:
-  workItemTypes:
-    - "User Story"
-    - "Product Backlog Item"
-  states:
-    - "New"
-    - "Approved"
-    - "Active"
-  tags:
-    include:
-      - "backend"
-      - "api"
-  excludeIfHasTasks: true
-
-# Task template with estimation percentages
-tasks:
-  - id: "design-api"
-    title: "Design API Specification"
-    description: |
-      Design RESTful API endpoints following company standards:
-      - Define request/response models
-      - Document in OpenAPI/Swagger
-      - Review with team architect
-    estimationPercent: 10
-    tags: ["design", "api"]
-    activity: "Design"
-
-  - id: "database-schema"
-    title: "Database Schema Changes"
-    description: |
-      Design and implement database changes:
-      - Create/update migrations
-      - Define models and relationships
-      - Index optimization
-    estimationPercent: 20
-    tags: ["database", "backend"]
-    activity: "Development"
-
-  - id: "implement-logic"
-    title: "Implement Business Logic"
-    description: |
-      Core API implementation:
-      - Implement service layer
-      - Add validation logic
-      - Error handling
-      - Logging
-    estimationPercent: 35
-    tags: ["implementation", "backend"]
-    activity: "Development"
-    dependsOn:
-      - "design-api"
-      - "database-schema"
-
-  - id: "unit-tests"
-    title: "Unit & Integration Tests"
-    description: |
-      Comprehensive test coverage:
-      - Unit tests (80%+ coverage)
-      - Integration tests
-      - Mock external dependencies
-    estimationPercent: 20
-    tags: ["testing", "quality"]
-    activity: "Testing"
-    dependsOn:
-      - "implement-logic"
-
-  - id: "documentation"
-    title: "API Documentation"
-    description: |
-      Update documentation:
-      - API endpoint documentation
-      - Update README
-      - Code comments
-      - Postman collection
-    estimationPercent: 5
-    tags: ["documentation"]
-    activity: "Documentation"
-
-  - id: "code-review"
-    title: "Code Review & Refinement"
-    description: |
-      Review and refine:
-      - Create pull request
-      - Address review feedback
-      - Final testing
-    estimationPercent: 10
-    tags: ["review", "quality"]
-    activity: "Design"
-
-# Estimation strategy
-estimation:
-  strategy: "percentage"
-  source: "Microsoft.VSTS.Scheduling.StoryPoints"
-  rounding: "nearest"
-  minimumTaskPoints: 0.5
-
-# Validation rules
-validation:
-  totalEstimationMustBe: 100
-  minTasks: 4
-  maxTasks: 10
-
-# Metadata
-metadata:
-  category: "Backend Development"
-  difficulty: "intermediate"
-  recommendedFor:
-    - "API features"
-    - "Microservices"
-    - "Backend services"
-  estimationGuidelines: |
-    Use this template for stories sized 3-13 points.
-    For larger stories, consider breaking down first.
-  examples:
-    - "User authentication API"
-    - "Payment processing endpoint"
-    - "Data export service"

package/examples/conditional-dependencies-template.yaml

@@ -1,145 +0,0 @@
-version: "1.0"
-name: "Full-Stack Development with Conditional Tasks"
-description: "Template demonstrating conditional tasks and dependencies"
-
-filter:
-  workItemTypes:
-    - "User Story"
-  tags:
-    include:
-      - "development"
-
-estimation:
-  rounding: "nearest"
-  minimumTaskPoints: 0.5
-
-tasks:
-  # Phase 1: Design (always runs)
-  - id: "design"
-    title: "UI/UX Design and Mockups"
-    description: "Create design mockups for ${story.title}"
-    estimationPercent: 15
-    activity: "Design"
-    assignTo: "@ParentAssignee"
-    tags:
-      - "design"
-
-  # Phase 2: Backend (conditional - only if story has backend tag)
-  - id: "backend-api"
-    title: "Backend API Implementation"
-    description: "Implement REST API endpoints for ${story.title}"
-    estimationPercent: 30
-    activity: "Development"
-    dependsOn: ["design"]
-    condition:
-      field: tags
-      operator: contains
-      value: backend
-    tags:
-      - "backend"
-      - "api"
-
-  # Phase 3: Frontend (conditional - only if story has frontend tag)
-  - id: "frontend-ui"
-    title: "Frontend UI Implementation"
-    description: "Build user interface for ${story.title}"
-    estimationPercent: 35
-    activity: "Development"
-    dependsOn: ["design"]
-    condition:
-      field: tags
-      operator: contains
-      value: frontend
-    tags:
-      - "frontend"
-
-  # Accessibility testing (conditional - only for frontend stories without legacy tag)
-  - id: "accessibility-testing"
-    title: "Accessibility Testing (WCAG)"
-    description: "Ensure UI meets accessibility standards for ${story.title}"
-    estimationPercent: 7
-    activity: "Testing"
-    dependsOn: ["frontend-ui"]
-    condition:
-      any:
-        - field: tags
-          operator: contains
-          value: frontend
-        - field: tags
-          operator: not-contains
-          value: legacy
-    tags:
-      - "accessibility"
-      - "testing"
-
-  # Security tasks (conditional - only for high-priority stories with security tag)
-  - id: "security-review"
-    title: "Security Review and Audit"
-    description: "Perform security review for ${story.title}"
-    estimationPercent: 8
-    activity: "Testing"
-    dependsOn: ["backend-api", "frontend-ui"]
-    condition:
-      all:
-        - field: tags
-          operator: contains
-          value: security
-        - field: priority
-          operator: lte
-          value: 2
-    priority: 1
-    tags:
-      - "security"
-
-  # Phase 4: Testing (depends on what was implemented)
-  - id: "unit-tests"
-    title: "Unit Tests"
-    description: "Write unit tests for ${story.title}"
-    estimationPercent: 15
-    activity: "Testing"
-    dependsOn: ["backend-api", "frontend-ui"]
-    tags:
-      - "testing"
-
-  - id: "integration-tests"
-    title: "Integration Tests"
-    description: "Write integration tests for ${story.title}"
-    estimationPercent: 12
-    activity: "Testing"
-    dependsOn: ["unit-tests"]
-    tags:
-      - "testing"
-
-  # Performance testing (conditional - only for stories with high estimation)
-  - id: "performance-tests"
-    title: "Performance and Load Testing"
-    description: "Conduct performance testing for ${story.title}"
-    estimationPercent: 10
-    activity: "Testing"
-    dependsOn: ["integration-tests"]
-    condition:
-      field: estimation
-      operator: gte
-      value: 13
-    tags:
-      - "performance"
-
-  # Phase 5: Documentation (always runs, depends on everything)
-  - id: "documentation"
-    title: "Technical Documentation"
-    description: "Write technical documentation for ${story.title}"
-    estimationPercent: 8
-    activity: "Documentation"
-    dependsOn: ["unit-tests"]
-    tags:
-      - "documentation"
-
-  # Deployment (final step, depends on all testing)
-  - id: "deployment"
-    title: "Deploy to Staging"
-    description: "Deploy ${story.title} to staging environment"
-    estimationPercent: 5
-    activity: "Deployment"
-    dependsOn: ["integration-tests", "documentation"]
-    tags:
-      - "deployment"