@sppg2001/atomize 5.1.0 → 5.1.2

package/README.md

@@ -1,11 +1,23 @@
 # Atomize CLI
 
-Atomize CLI turns stories into consistent child tasks using reusable YAML templates. It supports template validation, safe previews, confirmed task generation, connection profile management, template catalog operations, and CI/CD automation.
+**Break down stories, build up velocity.**
 
-Atomize is designed around platform adapters. Today, connected generation supports Azure DevOps. Mock is available for offline testing.
+Atomize turns Stories into consistent child Tasks using reusable YAML Templates. Capture your team's task breakdown once, then validate, preview, and reuse it from your terminal or CI/CD pipeline.
+
+- Try built-in Templates offline with Mock Stories.
+- Customize task titles, descriptions, conditions, dependencies, and estimation rules in YAML.
+- Reuse Templates and Mixins from built-in, user, and project Catalogs.
+- Draft and improve Templates with your GitHub Copilot account.
+- Preview real Azure DevOps Stories before confirming task creation.
+
+Connected generation currently supports **Azure DevOps**. Offline Validation and Mock Preview require no platform account or Connection Profile.
+
+[Website and documentation](https://atomize-docs.pages.dev/) · [CLI quickstart](https://atomize-docs.pages.dev/getting-started/cli/) · [Source and issues](https://github.com/Simao-Pereira-Gomes/atomize)
 
 ## Install
 
+Requires [Node.js](https://nodejs.org/) **22 or later** and npm.
+
 ```bash
 npm install -g @sppg2001/atomize
 ```
@@ -25,21 +37,28 @@ npx @sppg2001/atomize --help
 
 ## Quick Start
 
-Try Atomize without credentials:
+### Try it offline
+
+The `backend-api` Template ships with the CLI. Validate it, then preview a task breakdown using a Mock Story:
 
 ```bash
 atomize validate template:backend-api
-atomize generate template:backend-api --platform mock
+atomize preview template:backend-api \
+  --mock-story '{"id":"123","title":"Add password reset","estimation":8}'
 ```
 
-Connect Azure DevOps:
+The preview returns three Tasks: define API behavior, implement the change, and verify it. The example Template converts the Story Estimate of 8 into a 32-hour budget and splits it 20% / 50% / 30%. Change the title or estimate and run it again to see the breakdown change. No Work Items are created.
+
+### Connect Azure DevOps
+
+Add a Connection Profile using an Azure DevOps PAT with **Work Items read/write** access:
 
 ```bash
 atomize auth add work-ado
 atomize auth test work-ado
 ```
 
-Preview and then create tasks:
+Preview real Stories, then create Tasks after reviewing the plan:
 
 ```bash
 # Dry run, no tasks created
@@ -49,6 +68,8 @@ atomize generate template:backend-api --profile work-ado
 atomize generate template:backend-api --profile work-ado --execute
 ```
 
+Use `--story 123 456` to select specific Stories. See the [Auth Guide](https://atomize-docs.pages.dev/connections/profiles/) for PAT permissions, credential storage, and profile setup.
+
 ## Safety Model
 
 `atomize generate` is a dry run by default. It calculates the task plan but does not create tasks.
@@ -103,6 +124,20 @@ atomize fields list --type Task
 atomize queries list
 ```
 
+## AI-Assisted Authoring
+
+Use your signed-in GitHub Copilot account to draft a Template from prose or review a proposed improvement to an existing one:
+
+```bash
+atomize template create --ai
+atomize template improve template:backend-api
+
+# Draft with your team's written process as reference material
+atomize template create --ai --reference docs/how-we-work.md
+```
+
+AI authoring uses a separate Copilot Session; it does not require an Azure DevOps Connection Profile. You can explicitly add project context with `--ground --profile work-ado`. See [AI authoring](https://atomize-docs.pages.dev/cli/ai/) for sign-in, Reference Documents, and review workflows.
+
 ## CI/CD
 
 Validate first, then run live generation with explicit acknowledgement:
@@ -134,22 +169,23 @@ Validate first, then run live generation with explicit acknowledgement:
       --output report.json
 ```
 
-## VS Code Extension
+## Desktop and Editor Workflows
 
-Prefer an editor workflow? Atomize also has a VS Code extension for YAML authoring, validation, mock/live preview, profile management, catalog browsing, and confirmed generation.
+- **[Atomize Studio](https://github.com/Simao-Pereira-Gomes/atomize/blob/main/docs/Atomize-Studio.md)** is a standalone desktop app for visual Template authoring, Catalog management, and confirmed task generation. Download an installer via [Studio Releases](https://github.com/Simao-Pereira-Gomes/atomize/blob/main/docs/Studio-Releases.md).
+- **[VS Code extension](https://atomize-docs.pages.dev/getting-started/vscode/)** provides YAML completions, schema hovers, diagnostics, Mock and Live Preview, and confirmed generation in your editor.
 
-See the [VS Code Extension Guide](https://github.com/Simao-Pereira-Gomes/atomize/blob/main/docs/VS-Code-Extension.md).
+The CLI and Studio share Connection Profile metadata and compatible OS-keyring-backed tokens. VS Code manages its own profiles. See the [Auth Guide](https://atomize-docs.pages.dev/connections/profiles/#shared-between-the-cli-and-atomize-studio) for details.
 
 ## Documentation
 
-- [Product README](https://github.com/Simao-Pereira-Gomes/atomize#readme) - VS Code-first onboarding and product overview
-- [Documentation Index](https://github.com/Simao-Pereira-Gomes/atomize/blob/main/docs/README.md)
-- [Workflows](https://github.com/Simao-Pereira-Gomes/atomize/blob/main/docs/Workflows.md)
-- [CLI Reference](https://github.com/Simao-Pereira-Gomes/atomize/blob/main/docs/Cli-Reference.md)
-- [Template Creation](https://github.com/Simao-Pereira-Gomes/atomize/blob/main/docs/Template-Creation.md)
-- [Template Reference](https://github.com/Simao-Pereira-Gomes/atomize/blob/main/docs/Template-Reference.md)
-- [Auth Guide](https://github.com/Simao-Pereira-Gomes/atomize/blob/main/docs/Auth-Guide.md)
-- [Platform Guide](https://github.com/Simao-Pereira-Gomes/atomize/blob/main/docs/Platform-Guide.md)
+- [Website and Documentation](https://atomize-docs.pages.dev/)
+- [Workflows](https://atomize-docs.pages.dev/workflows/)
+- [CLI Reference](https://atomize-docs.pages.dev/cli/reference/)
+- [Template Creation](https://atomize-docs.pages.dev/catalog/create/)
+- [Schema Reference](https://atomize-docs.pages.dev/reference/templates/schema/)
+- [Template Reference](https://atomize-docs.pages.dev/reference/templates/)
+- [Auth Guide](https://atomize-docs.pages.dev/connections/profiles/)
+- [Platform Guide](https://atomize-docs.pages.dev/connections/)
 
 ## License
 

package/catalog/mixins/documentation.atomize.yaml

@@ -1,5 +1,7 @@
+formatVersion: "1.0"
 name: "Documentation Tasks"
-description: "Standard documentation tasks. Mix into any template to ensure docs are part of the definition of done."
+description: "Example documentation tasks. Add the tasks relevant to your change and adapt their estimates."
+# Illustrative percentages add to the consuming Template; rebalance its total.
 tasks:
   - id: "update-docs"
     title: "Update Documentation: ${story.title}"
@@ -13,4 +15,4 @@ tasks:
     description: "Add a clear, user-focused entry to the project changelog describing what changed and why."
     estimationPercent: 5
     activity: "Documentation"
-    assignTo: "@ParentAssignee"
+    assignTo: "@Unassigned"

package/catalog/mixins/security-review.atomize.yaml

@@ -1,16 +1,18 @@
+formatVersion: "1.0"
 name: "Security Review Tasks"
-description: "Common security review tasks. Mix into any feature template to enforce a security gate."
+description: "Example security tasks. Adapt the scope and estimates to the risks relevant to your change."
+# Illustrative percentages add to the consuming Template; rebalance its total.
 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)."
+    description: "Review security concerns relevant to the change, such as access control or handling sensitive data."
     estimationPercent: 10
-    activity: "Design"
+    activity: "Development"
     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)."
+    description: "Check changed dependencies for known vulnerabilities using tools appropriate to the project."
     estimationPercent: 5
     activity: "Development"
     assignTo: "@Unassigned"

package/catalog/mixins/test-coverage.atomize.yaml

@@ -1,19 +1,21 @@
+formatVersion: "1.0"
 name: "Test Coverage Tasks"
-description: "Expanded testing tasks. Mix into any template to enforce unit, integration, and E2E test coverage."
+description: "Example testing tasks, including a conditional task. Choose the test types and estimates relevant to your change."
+# Illustrative percentages add to the consuming Template; rebalance its total.
 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."
+    description: "Write unit tests covering the core logic and edge cases."
     estimationPercent: 15
     activity: "Testing"
-    assignTo: "@ParentAssignee"
+    assignTo: "@Unassigned"
 
   - 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"]
+    assignTo: "@Unassigned"
 
   - id: "e2e-tests"
     title: "End-to-End Tests: ${story.title}"
@@ -21,6 +23,7 @@ tasks:
     estimationPercent: 10
     activity: "Testing"
     assignTo: "@Unassigned"
+    # Example opt-in tag; replace it with your own condition if needed.
     condition:
       field: "tags"
       operator: "contains"

package/catalog/templates/agile-story-breakdown.atomize.yaml

@@ -1,214 +1,63 @@
 formatVersion: "1.0"
 name: "Agile Story Breakdown"
-description: "Agile story breakdown template. Handles dev stories, mixed dev+test stories, and test-only stories in a single template using conditional tasks and conditional estimation."
+description: "Example of conditional tasks and estimates. Adapt the tasks and illustrative tag to your team's workflow."
 author: "Atomize"
-tags: []
 
 filter:
+  # Change this to the Work Item type used by your project.
   workItemTypes: ["User Story"]
-  states: ["Ready for Sprint"]
-  tags:
-    exclude:
-      - "TestGen"
   excludeIfHasTasks: true
-  areaPaths:
-    - EA-RSP-Platform\Release 2 Team
-  iterations:
-    - "@CurrentIteration"
+  # Alternative: let an existing Azure DevOps query select the Stories.
+  # Uncomment savedQuery and replace its path with a query in your project.
+  # workItemTypes then declares the types returned; it does not filter the query.
+  # savedQuery:
+  #   path: "Shared Queries/Example"
 
 tasks:
-  - title: "Analysis & Playback"
-    estimationPercent: 20
+  - id: "implement"
+    title: "Implement: ${story.title}"
+    description: "Make the changes needed to meet the acceptance criteria."
+    estimationPercent: 60
     activity: "Development"
-    tags: []
     assignTo: "@ParentAssignee"
+    # Example convention: this tag selects verification work only.
     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
+      field: tags
+      operator: not-contains
+      value: verification-only
 
-  - title: "Test Preparation"
+  - id: "verify"
+    title: "Verify: ${story.title}"
+    description: "Check the outcome against the acceptance criteria."
     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
+          field: tags
+          operator: contains
+          value: verification-only
+        percent: 100
 
 estimation:
   strategy: "percentage"
   rounding: "none"
-  minimumTaskEstimate: 0
+  ifParentHasNoEstimation: "warn"
+
+# These are authoring checks, not a count of tasks after conditions run.
+validation:
+  totalEstimationMustBe: 100
+  minTasks: 1
+  maxTasks: 5
 
 metadata:
-  category: "Agile Project"
+  category: "Examples"
   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
+    The 60/40 split is illustrative. A Story tagged verification-only generates
+    just the verification Task with 100% of the converted Story Estimate.
+    Replace the tag and percentages to suit your own work.
+  notes: |
+    This example demonstrates conditions, not a required delivery process.
+    Copy it into your Catalog and adapt the Work Item type, tasks, and estimates.
+    Activities and assignment tokens are illustrative; adapt them to your
+    project. The commented saved-query alternative demonstrates query selection.

package/catalog/templates/backend-api.atomize.yaml

@@ -1,58 +1,57 @@
 formatVersion: "1.0"
 name: "Backend API Development"
-description: "Standard backend API development with database integration"
+description: "Example API task breakdown with Story Estimate conversion. Adapt it to your interface, implementation, and verification needs."
 author: "Atomize"
-tags: ["backend", "api", "database"]
+tags: ["example", "api"]
 
 filter:
+  # Change this to the Work Item type used by your project.
   workItemTypes: ["User Story"]
-  states: ["New", "Active", "Approved"]
-  tags:
-    include: ["backend", "api"]
   excludeIfHasTasks: true
 
 tasks:
-  - title: "Design API Endpoints: ${story.title}"
-    description: "Design REST API endpoints, request/response schemas, and error handling"
-    estimationPercent: 15
+  - id: "design"
+    title: "Define API Behavior: ${story.title}"
+    description: "Describe the inputs, outputs, and expected behavior relevant to this change."
+    estimationPercent: 20
     activity: "Design"
-    tags: ["design", "api"]
+    assignTo: "@ParentAssignee"
 
-  - title: "Database Schema: ${story.title}"
-    description: "Design and create database tables, migrations, and relationships"
-    estimationPercent: 15
-    activity: "Design"
-    tags: ["database", "migration"]
-
-  - title: "Implement Core Logic: ${story.title}"
-    description: "Implement business logic, data validation, and error handling"
-    estimationPercent: 35
+  - id: "implement"
+    title: "Implement API Change: ${story.title}"
+    description: "Make the changes needed for the agreed behavior."
+    estimationPercent: 50
     activity: "Development"
-    tags: ["implementation"]
-
-  - title: "Write Unit Tests"
-    description: "Unit tests for services, repositories, and utilities"
-    estimationPercent: 15
-    activity: "Testing"
-    tags: ["testing", "unit-tests"]
+    assignTo: "@ParentAssignee"
+    dependsOn: ["design"]
 
-  - title: "Integration Tests & Documentation"
-    description: "API integration tests and OpenAPI/Swagger documentation"
-    estimationPercent: 10
+  - id: "verify"
+    title: "Verify API Behavior: ${story.title}"
+    description: "Check expected results, error cases, and compatibility where relevant."
+    estimationPercent: 30
     activity: "Testing"
-    tags: ["testing", "documentation"]
-
-  - title: "Code Review & Refinement"
-    description: "Address code review feedback and refactor as needed"
-    estimationPercent: 10
-    activity: "Documentation"
-    tags: ["review"]
+    assignTo: "@Unassigned"
+    dependsOn: ["implement"]
 
 estimation:
   strategy: "percentage"
+  # Example: one Story Estimate unit becomes four Task Estimate units.
+  conversion:
+    factor: 4
+  # Alternative for a discrete or non-linear scale: replace factor with a table.
+  # conversion:
+  #   table: { "1": 2, "2": 5, "3": 8, "5": 16 }
   rounding: "nearest"
-  minimumTaskEstimate: 0
+  ifParentHasNoEstimation: "warn"
+
+validation:
+  totalEstimationMustBe: 100
 
 metadata:
-  category: "Backend"
-  estimationGuidelines: "Based on typical backend development workflows"
+  category: "Examples"
+  estimationGuidelines: "The factor of 4 and 20/50/30 split are illustrative. Convert the Story Estimate first, distribute it, then round to the nearest half Task unit. Use the commented table alternative for a non-linear scale."
+  notes: |
+    Copy and adapt this example. It assumes no particular API style, database,
+    test framework, documentation tool, or workflow state. Activity names and
+    assignment choices are illustrative; adapt them to your project.
+    Change the Work Item type and add or remove tasks to fit your project.

package/catalog/templates/bug-fix.atomize.yaml

@@ -1,32 +1,25 @@
 formatVersion: "1.0"
 name: "Bug Fix"
-description: "Foundation for bug-fix templates. Extend this to inherit a standard investigation and fix task set."
+description: "Example fixed Task Estimates for investigation, fix, and verification. Copy or extend it to fit how your team handles bugs."
 author: "Atomize"
-tags: ["template", "bug"]
+tags: ["example", "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
+    estimationFixed: 1
     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
+    estimationFixed: 2
     activity: "Development"
     assignTo: "@ParentAssignee"
     dependsOn: ["investigate"]
@@ -34,21 +27,32 @@ tasks:
   - id: "verify"
     title: "Verify Fix: ${story.title}"
     description: "Verify the fix resolves the issue and does not introduce regressions."
-    estimationPercent: 20
+    estimationFixed: 1
     activity: "Testing"
+    assignTo: "@Unassigned"
     dependsOn: ["fix"]
 
   - id: "close"
-    title: "Close & Document: ${story.title}"
-    description: "Update documentation, close the bug, and notify stakeholders."
-    estimationPercent: 10
+    title: "Record Outcome: ${story.title}"
+    description: "Record the outcome and any follow-up information useful to your team."
+    estimationFixed: 0.5
     activity: "Documentation"
+    assignTo: "@ParentAssignee"
     dependsOn: ["verify"]
 
-estimation:
-  strategy: "percentage"
-  rounding: "none"
-  ifParentHasNoEstimation: "warn"
-
+# Fixed estimates use the Task's unit and do not depend on a Story Estimate.
+# These example limits check the fixed estimates, rather than a percentage total.
 validation:
-  totalEstimationMustBe: 100
+  minTasks: 1
+  maxTasks: 10
+  taskEstimationRange:
+    min: 0.5
+    max: 8
+
+metadata:
+  category: "Examples"
+  estimationGuidelines: "Fixed values are illustrative, in the Task unit (typically hours). They are independent of the Story Estimate and bypass percentage rounding."
+  notes: |
+    Copy and adapt the Work Item type, tasks, dependencies, and estimates.
+    Adapt the activity names to your project. Assignment tokens illustrate
+    inheriting the Story assignee and leaving verification unassigned.