@sppg2001/atomize 1.2.4 → 2.0.0-alpha.0

package/docs/Cli-Reference.md

@@ -0,0 +1,962 @@
+# Atomize CLI Reference
+
+Complete command-line interface documentation for Atomize v2.0.0-alpha.0.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Global Options](#global-options)
+- [Commands Overview](#commands-overview)
+- [Command Reference](#command-reference)
+  - [auth](#auth)
+  - [generate](#generate)
+  - [fields](#fields)
+  - [validate](#validate)
+  - [template create](#template-create)
+  - [template list](#template-list)
+  - [template install](#template-install)
+  - [template remove](#template-remove)
+  - [template resolve](#template-resolve)
+  - [queries list](#queries-list)
+- [Configuration](#configuration)
+- [Interactive Prompts & Navigation](#interactive-prompts--navigation)
+- [Examples](#examples)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Installation
+
+```bash
+# Global installation (recommended)
+npm install -g @sppg2001/atomize
+
+# Install the alpha
+npm install -g @sppg2001/atomize@alpha
+
+# Verify installation
+atomize --version
+
+# Show help
+atomize --help
+```
+
+**Aliases:** Both `atomize` and `atom` work as the CLI command.
+
+---
+
+## Global Options
+
+These options work with any command:
+
+| Option | Description |
+|--------|-------------|
+| `--version` | Print the installed version |
+| `--help` | Show help for a command |
+| `--env-file <path>` | Load environment variables from a file before running the command (shell environment takes precedence over file values) |
+
+---
+
+## Commands Overview
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `auth` | - | Manage named connection profiles |
+| `auth add` | - | Add a new connection profile |
+| `auth list` | `auth ls` | List all saved profiles |
+| `auth use` | - | Set a profile as the default |
+| `auth remove` | `auth rm` | Remove a profile |
+| `auth test` | - | Test connectivity for a profile |
+| `auth rotate` | - | Replace the PAT for a profile |
+| `generate` | `gen` | Generate tasks from user stories using a template |
+| `fields` | - | Browse Azure DevOps work item fields |
+| `fields list` | `fields ls` | List available fields for the current project or work item type |
+| `validate` | - | Validate a template file |
+| `template` | `tpl` | Template management commands |
+| `template create` | - | Create a new template interactively or with AI |
+| `template list` | `template ls` | List available templates and mixins from the catalog |
+| `template install` | - | Install a template or mixin from a local file or HTTPS URL |
+| `template remove` | `template rm` | Remove a user-installed template or mixin |
+| `template resolve` | - | Resolve a composed template and print the merged result |
+| `queries` | - | Browse Azure DevOps saved queries |
+| `queries list` | `queries ls` | List saved queries with paths and IDs |
+
+---
+
+## Command Reference
+
+### auth
+
+Manage named connection profiles. Profiles store your credentials in the OS keychain when available. If the keychain is unavailable, `--insecure-storage` opts into an insecure local file fallback at `~/.atomize/`.
+
+Two profile types are supported:
+- **Azure DevOps** — for `generate`, `validate`, `fields list`, and `queries list`
+- **GitHub Models (AI)** — for AI-assisted template generation (`template create --ai`)
+
+#### auth add
+
+Add a new connection profile.
+
+```bash
+atomize auth add [name] [options]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--org-url <url>` | Organization URL (e.g. `https://dev.azure.com/myorg`) — Azure DevOps only |
+| `--project <name>` | Project name — Azure DevOps only |
+| `--team <name>` | Team name — Azure DevOps only |
+| `--default` | Set this profile as the default for its platform |
+| `--pat-stdin` | Read the PAT from stdin instead of `ATOMIZE_PAT` (preferred in CI) |
+| `--insecure-storage` | Allow storing the token in an insecure local file fallback when the OS keychain is unavailable |
+
+When run interactively, `auth add` first asks which platform to configure:
+
+```
+? Platform:
+  ● Azure DevOps
+  ○ GitHub Models (AI template generation)
+```
+
+**Adding an Azure DevOps profile:**
+```bash
+atomize auth add work-ado
+# Prompts for org URL, project, team, and PAT
+```
+
+**Adding a GitHub Models (AI) profile:**
+```bash
+atomize auth add my-ai
+# Prompts for a GitHub personal access token with Models access
+```
+
+**Non-interactive (Azure DevOps, CI/CD):**
+```bash
+echo "$AZURE_DEVOPS_PAT" | atomize auth add work-ado \
+  --org-url https://dev.azure.com/myorg \
+  --project MyProject \
+  --team MyTeam \
+  --default \
+  --pat-stdin
+```
+
+Profile names may contain letters, numbers, hyphens, and underscores.
+
+---
+
+#### auth list
+
+List all saved connection profiles.
+
+```bash
+atomize auth list
+atomize auth ls   # alias
+```
+
+**Output:**
+```
+  work-ado (Azure DevOps · default)
+    URL:      https://dev.azure.com/myorg
+    Project:  MyProject
+    Team:     MyTeam
+    Token:    [keychain]
+    Created:  1/3/2026, 10:00:00 AM
+
+  my-ai (GitHub Models (AI) · default)
+    Token:    [keychain]
+    Created:  1/3/2026, 10:05:00 AM
+```
+
+---
+
+#### auth use
+
+Set a profile as the default for its platform. Each platform (`azure-devops`, `github-models`) can have its own independent default.
+
+```bash
+atomize auth use [name]
+```
+
+```bash
+atomize auth use work-ado   # sets default Azure DevOps profile
+atomize auth use my-ai      # sets default GitHub Models (AI) profile
+atomize auth use            # pick interactively
+```
+
+---
+
+#### auth remove
+
+Remove a saved connection profile.
+
+```bash
+atomize auth remove [name]
+atomize auth rm [name]   # alias
+```
+
+---
+
+#### auth test
+
+Test connectivity for a profile. Automatically detects whether the profile is an Azure DevOps or GitHub Models (AI) profile and runs the appropriate check.
+
+- **Azure DevOps** — executes a WIQL query against your project to verify credentials and project access
+- **GitHub Models (AI)** — calls the models listing endpoint to verify the token
+
+```bash
+atomize auth test [name]
+```
+
+```bash
+atomize auth test work-ado   # test a specific profile
+atomize auth test my-ai      # test an AI provider profile
+atomize auth test            # pick interactively (shows profile type next to each name)
+```
+
+---
+
+#### auth rotate
+
+Replace the stored PAT for a profile (e.g. after a token expires).
+
+```bash
+atomize auth rotate [name]
+```
+
+---
+
+### generate
+
+Generate tasks from user stories using a template. By default runs as a dry run (preview only). Use `--execute` to actually create tasks.
+
+#### Usage
+
+```bash
+atomize generate [template] [options]
+atomize gen [template] [options]  # alias
+```
+
+#### Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `[template]` | Path to a YAML template file or catalog ref (e.g. `template:backend-api`). If omitted, you will be prompted. |
+
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `-p, --platform <platform>` | string | `azure-devops` | Platform to use. Options: `azure-devops`, `mock` |
+| `--profile <name>` | string | - | Named connection profile to use (see `auth add`) |
+| `--execute` | flag | - | Actually create tasks (default is dry-run preview) |
+| `--auto-approve` | flag | - | Required with `--execute` in non-interactive mode to acknowledge live task creation |
+| `--continue-on-error` | flag | - | Keep processing other stories if one fails |
+| `--story <ids...>` | string[] | - | Target specific work items by ID, bypassing the template filter. `excludeIfHasTasks` still applies. |
+| `--story-concurrency <n>` | number | `3` | Max stories processed in parallel (max: 10) |
+| `--task-concurrency <n>` | number | `5` | Max tasks created in parallel per story (max: 20) |
+| `--dependency-concurrency <n>` | number | `5` | Max dependency links created in parallel (max: 10) |
+| `--limit <n>` | number | - | Cap the number of work items processed (useful for testing before a full `--execute` run) |
+| `-v, --verbose` | flag | - | Show detailed output including per-task breakdown |
+| `-o, --output <file>` | string | - | Write a JSON report to this file path (for CI/CD) |
+| `--include-sensitive-report-data` | flag | - | Include descriptions, custom fields, and platform-specific work item data in the JSON report (`--output` only) |
+| `-q, --quiet` | flag | - | Suppress non-essential output |
+
+#### Examples
+
+**Dry run (default — no --execute):**
+```bash
+atomize generate template:backend-api
+```
+
+**Execute for real:**
+```bash
+atomize generate template:backend-api --execute
+```
+
+**Target specific stories by ID (bypasses filter):**
+```bash
+atomize generate template:backend-api --story STORY-123 STORY-456
+```
+
+Use `--story` to skip the template's `filter` criteria and process explicit work items directly. Useful for:
+- Re-running a generation that failed partway through
+- Processing a one-off story that does not match the template's usual filter
+- Testing the template against a known story before a full run
+
+`excludeIfHasTasks` still applies — stories that already have tasks are skipped unless you remove that flag from the template.
+
+**Execute for real in CI/non-interactive mode:**
+```bash
+atomize generate template:backend-api --execute --auto-approve
+```
+
+**Mock platform (no credentials needed):**
+```bash
+atomize generate template:backend-api --platform mock
+```
+
+**Test against a subset of items before a full run:**
+```bash
+atomize generate template:backend-api --limit 5
+```
+
+**CI/CD with JSON report:**
+```bash
+atomize generate template:backend-api \
+  --execute \
+  --output report.json \
+  --quiet
+```
+
+By default the JSON report omits story descriptions, custom field values, and raw platform payloads to avoid accidentally writing sensitive data to disk or log collectors. Pass `--include-sensitive-report-data` to include them:
+
+```bash
+atomize generate template:backend-api \
+  --execute \
+  --output report.json \
+  --include-sensitive-report-data
+```
+
+When to use `--include-sensitive-report-data`:
+- Debugging unexpected task output (custom field values, description interpolation)
+- Auditing exactly what was sent to the platform
+- Internal tooling that processes the full report programmatically
+
+Do not use it in shared CI pipelines where the report artifact may be visible to other users.
+
+#### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | All stories processed successfully |
+| `1` | One or more stories failed |
+
+---
+
+### validate
+
+Validate a template file for correctness and completeness.
+
+#### Usage
+
+```bash
+atomize validate <template> [options]
+```
+
+#### Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `<template>` | Path to a YAML template file or HTTPS URL. **Required.** |
+
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `-s, --strict` | flag | - | Use strict mode: warnings are treated as errors |
+| `-q, --quiet` | flag | - | Suppress non-essential output |
+| `--profile <name>` | string | - | Connect to ADO using a named profile for live saved-query and custom-field validation |
+
+> See [Validation Modes](./Validation-Modes.md) for a full explanation of strict vs lenient behavior.
+
+**Validation modes for ADO-backed features:**
+- Without `--profile`, validation runs offline and checks template structure only
+- With `--profile`, Atomize connects to ADO to validate task `customFields`, custom fields referenced in task conditions, and `filter.savedQuery`
+- In interactive terminals, if ADO-backed validation is needed, Atomize can prompt you to choose offline vs online validation
+- In `--strict` mode, offline custom-field verification warnings are promoted to errors
+
+#### Examples
+
+```bash
+atomize validate template:backend-api
+atomize validate template:backend-api --strict
+atomize validate template:backend-api --profile work-ado
+atomize validate https://example.com/templates/shared.yaml
+```
+
+#### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Template is valid |
+| `1` | Template validation failed |
+
+---
+
+### fields
+
+Browse Azure DevOps work item fields available to the current profile.
+
+#### fields list
+
+```bash
+atomize fields list [options]
+atomize fields ls   # alias
+```
+
+| Option | Description |
+|--------|-------------|
+| `--type <WorkItemType>` | Scope results to a specific work item type such as `Task` or `Bug` |
+| `--custom-only` | Show only custom fields (`Custom.*`) |
+| `--profile <name>` | Named connection profile to use (uses default if omitted) |
+| `--json` | Print results as JSON to stdout; progress messages go to stderr |
+
+**Examples:**
+
+```bash
+atomize fields list
+atomize fields list --type Task
+atomize fields list --type Task --custom-only
+atomize fields list --type Task --json > task-fields.json
+```
+
+---
+
+### template create
+
+Create a new template or mixin using one of several methods.
+
+#### Usage
+
+```bash
+atomize template create [options]
+atomize tpl create [options]  # alias
+```
+
+#### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `--type <type>` | string | Create a `template` or a `mixin` (prompted if omitted) |
+| `--from <name>` | string | Start from an existing catalog template |
+| `--from-stories <ids>` | string | Learn template from multiple stories (comma-separated IDs) |
+| `--scratch` | flag | Jump directly to the interactive wizard (skips mode selection) |
+| `--ai` | flag | Use AI-assisted generation — describe the template in natural language |
+| `--ground` | flag | Ground AI generation with patterns from your Azure DevOps workspace |
+| `--ai-profile <name>` | string | AI provider profile to use (uses default GitHub Models profile if omitted) |
+| `--save-as <name>` | string | Name to save the template under in the catalog |
+| `--profile <name>` | string | Named ADO profile for `--from-stories` and field suggestions (uses default if omitted) |
+| `-p, --platform <platform>` | string | Platform for `--from-stories` (default: `azure-devops`) |
+| `-q, --quiet` | flag | Suppress non-essential output |
+
+#### Creation Modes
+
+**1. From Catalog Template**
+
+Start from a built-in or previously installed template.
+
+```bash
+atomize template create --from backend-api
+atomize template create --from my-custom-template
+```
+
+Use `atomize template list` to see available names.
+
+---
+
+**2. AI-Assisted Generation**
+
+Describe the template you need in plain language and let AI generate it.
+
+```bash
+# Basic AI generation
+atomize template create --ai
+
+# Ground with real patterns from your ADO workspace
+atomize template create --ai --ground --profile work-ado
+
+# Specify which AI profile to use
+atomize template create --ai --ai-profile my-ai
+```
+
+Requires a GitHub Models profile (`atomize auth add` → select GitHub Models).
+
+---
+
+**3. Learn from Multiple Stories**
+
+Analyze existing stories to detect patterns and build a higher-confidence template.
+
+```bash
+atomize template create --from-stories STORY-1,STORY-2,STORY-3
+
+atomize template create \
+  --from-stories STORY-123,STORY-456,STORY-789 \
+  --save-as api-pattern
+```
+
+See [Story Learner](./Story-Learner.md) for details.
+
+---
+
+**4. Interactive Wizard (From Scratch)**
+
+Step-by-step guided builder for full control.
+
+```bash
+atomize template create --scratch
+```
+
+The wizard walks through basic information, filter configuration, task configuration (including composition — inheritance and mixins), estimation settings, validation rules, and metadata.
+
+---
+
+#### Creating Mixins
+
+A mixin is a reusable group of tasks that can be mixed into multiple templates via the `mixins:` field. Use `--type mixin` to create one.
+
+```bash
+atomize template create --type mixin
+atomize template create --type mixin --save-as security-review-tasks
+```
+
+See [Template Reference — Composition](./Template-Reference.md#composition) for how to use mixins.
+
+---
+
+### template list
+
+List available templates and mixins from the catalog (built-in and user-installed).
+
+#### Usage
+
+```bash
+atomize template list [options]
+atomize template ls   # alias
+atomize tpl ls        # alias
+```
+
+#### Options
+
+| Option | Description |
+|--------|-------------|
+| `--type <type>` | Filter by type: `template` or `mixin` |
+
+#### Output
+
+```
+Built-in Templates
+
+  backend-api
+    Backend API Development
+    Standard backend API development with database integration
+
+  feature
+    Feature Template
+    Foundation for feature templates
+
+  bug
+    Bug Template
+    Foundation for bug-fix templates
+
+  custom
+    Custom Example
+    Example template with custom fields
+
+User Templates
+
+  my-api-template
+    My API Template
+    (no description)
+
+Use with: atomize generate template:<name>
+         atomize template create --from <name>
+```
+
+---
+
+### template install
+
+Install a template or mixin from a local file or HTTPS URL into the catalog.
+
+#### Usage
+
+```bash
+atomize template install <source> [options]
+```
+
+#### Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `<source>` | Path to a local YAML file or an HTTPS URL |
+
+#### Options
+
+| Option | Description |
+|--------|-------------|
+| `--type <type>` | Force type: `template` or `mixin` (auto-detected from file content if omitted) |
+| `--overwrite` | Overwrite if a template with the same name already exists |
+| `--scope <scope>` | Installation scope: `user` (default, `~/.atomize`) or `project` (`.atomize` in current directory) |
+
+#### Examples
+
+```bash
+# Install from a local file
+atomize template install ./templates/my-api.yaml
+
+# Install from a URL (shared team template)
+atomize template install https://example.com/templates/security-review.yaml
+
+# Install as project-scoped (stored in .atomize/ next to your code)
+atomize template install ./templates/sprint-tasks.yaml --scope project
+
+# Overwrite an existing template
+atomize template install ./templates/backend-api.yaml --overwrite
+```
+
+**Scopes:**
+- `user` (default) — installed to `~/.atomize/templates/`, available across all projects
+- `project` — installed to `.atomize/templates/` in the current directory, scoped to this repo
+
+---
+
+### template remove
+
+Remove a user-installed template or mixin from the catalog. Built-in templates cannot be removed.
+
+#### Usage
+
+```bash
+atomize template remove <name> [options]
+atomize template rm <name> [options]   # alias
+```
+
+#### Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `<name>` | Template ref (`template:<name>` or `mixin:<name>`) or bare name |
+
+#### Options
+
+| Option | Description |
+|--------|-------------|
+| `--type <type>` | Restrict to a specific type: `template` or `mixin` |
+| `-f, --force` | Skip confirmation prompt |
+
+#### Examples
+
+```bash
+atomize template remove my-api-template
+atomize template remove mixin:security-tasks
+atomize template remove my-api-template --force
+```
+
+---
+
+### template resolve
+
+Resolve a composed template (one that uses `extends` or `mixins`) and print the fully merged YAML. Useful for debugging composition and verifying the final template before use.
+
+#### Usage
+
+```bash
+atomize template resolve <template> [options]
+```
+
+#### Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `<template>` | Template ref (`template:<name>`) or path to a YAML file |
+
+#### Options
+
+| Option | Description |
+|--------|-------------|
+| `--validate` | Also run schema validation on the resolved template |
+| `-q, --quiet` | Print only the resolved YAML, no decorative output |
+
+#### Examples
+
+```bash
+# Resolve and preview a composed template
+atomize template resolve template:my-api
+
+# Resolve from a file
+atomize template resolve ./templates/composed.yaml
+
+# Resolve, validate, and pipe to a file
+atomize template resolve template:my-api --quiet > resolved.yaml
+
+# Resolve and validate in one step
+atomize template resolve template:my-api --validate
+```
+
+---
+
+### queries
+
+Browse Azure DevOps saved queries — discover query paths and IDs without leaving the terminal.
+
+#### queries list
+
+```bash
+atomize queries list [options]
+atomize queries ls   # alias
+```
+
+| Option | Description |
+|--------|-------------|
+| `--folder <path>` | Scope results to queries under this folder path prefix |
+| `--profile <name>` | Named connection profile to use (uses default if omitted) |
+| `--json` | Print results as JSON to stdout; progress messages go to stderr |
+
+**Examples:**
+
+```bash
+atomize queries list
+atomize queries list --folder "Shared Queries/Teams/Backend"
+atomize queries list --json | jq '.[] | select(.isPublic) | .path'
+```
+
+---
+
+## Configuration
+
+### Connection Profiles
+
+Credentials are managed as named profiles. Each platform has its own independent default profile.
+
+```bash
+# Add an Azure DevOps profile
+atomize auth add work-ado
+atomize auth use work-ado   # set as default ADO profile
+
+# Add a GitHub Models (AI) profile
+atomize auth add my-ai
+atomize auth use my-ai      # set as default AI profile
+
+# Test both
+atomize auth test work-ado
+atomize auth test my-ai
+```
+
+### Environment Variables
+
+**Authentication:**
+
+```bash
+export ATOMIZE_PAT="your-personal-access-token"          # Used by auth add
+```
+
+**Profile selection:**
+
+```bash
+export ATOMIZE_PROFILE="work-ado"       # Azure DevOps profile
+export ATOMIZE_AI_PROFILE="my-ai"       # GitHub Models (AI) profile
+```
+
+Profile resolution order for ADO commands (`generate`, `fields list`, `queries list`, `validate --profile`):
+1. `--profile <name>` flag
+2. `ATOMIZE_PROFILE` environment variable
+3. Default ADO profile (set via `atomize auth use`)
+
+Profile resolution order for AI commands (`template create --ai`):
+1. `--ai-profile <name>` flag
+2. `ATOMIZE_AI_PROFILE` environment variable
+3. Default GitHub Models profile (set via `atomize auth use`)
+
+**Logging:**
+
+```bash
+export LOG_LEVEL="info"   # debug, info, warn, error
+```
+
+### .env File
+
+No `.env` file is loaded automatically. Use the global `--env-file` flag to load one explicitly:
+
+```bash
+atomize --env-file .env.work generate template:backend-api
+atomize --env-file /etc/atomize/ci.env generate template:backend-api --execute --auto-approve
+```
+
+Shell environment variables always take precedence over values in the file.
+
+Example `.env` file:
+
+```bash
+ATOMIZE_PROFILE=work-ado
+```
+
+---
+
+## Interactive Prompts & Navigation
+
+| Key | Action |
+|-----|--------|
+| `↑` / `↓` | Navigate between options in a list |
+| `Enter` | Confirm selection or submit input |
+| `Space` | Toggle selection (in multi-select prompts) |
+| `Ctrl+C` | Cancel the current operation and exit |
+
+---
+
+## Examples
+
+### Complete Workflow: Azure DevOps
+
+```bash
+# 1. Save your Azure DevOps credentials
+atomize auth add work-ado
+atomize auth use work-ado
+
+# 2. Verify the connection
+atomize auth test work-ado
+
+# 3. Browse available templates
+atomize template list
+
+# 4. Start from a catalog template
+atomize template create --from backend-api --save-as my-backend
+
+# 5. Validate it
+atomize validate my-backend.yaml
+
+# 6. Preview (dry run)
+atomize generate my-backend.yaml
+
+# 7. Execute
+atomize generate my-backend.yaml --execute
+```
+
+### AI-Assisted Template Creation
+
+```bash
+# 1. Add a GitHub Models profile
+atomize auth add my-ai
+atomize auth use my-ai
+
+# 2. Describe your template to the AI
+atomize template create --ai
+
+# 3. Optionally ground it with real ADO patterns
+atomize template create --ai --ground --profile work-ado
+```
+
+### Multi-Story Learning
+
+```bash
+atomize template create \
+  --from-stories STORY-1,STORY-2,STORY-3,STORY-4,STORY-5 \
+  --platform azure-devops
+```
+
+### Using Composed Templates
+
+```bash
+# Install a shared mixin from a URL
+atomize template install https://example.com/mixins/security-review.yaml
+
+# Resolve and inspect a composed template
+atomize template resolve template:my-api
+
+# Validate a composed template
+atomize template resolve template:my-api --validate
+```
+
+### Target Specific Stories
+
+```bash
+# Run only against specific story IDs (bypasses filter)
+atomize generate template:backend-api --story STORY-101 STORY-102 STORY-103
+```
+
+### CI/CD Integration
+
+```yaml
+# .github/workflows/generate-tasks.yml
+jobs:
+  generate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Atomize
+        run: npm install -g @sppg2001/atomize@alpha
+
+      - name: Save connection profile
+        run: |
+          echo "${{ secrets.AZURE_DEVOPS_PAT }}" | atomize auth add ci \
+            --org-url "${{ secrets.AZURE_DEVOPS_ORG_URL }}" \
+            --project "${{ secrets.AZURE_DEVOPS_PROJECT }}" \
+            --team "${{ secrets.AZURE_DEVOPS_TEAM }}" \
+            --default \
+            --pat-stdin \
+            --insecure-storage
+
+      - name: Validate Templates
+        run: |
+          for template in templates/*.yaml; do
+            atomize validate "$template" --strict --quiet
+          done
+
+      - name: Generate Tasks
+        run: |
+          atomize generate template:backend-api \
+            --execute \
+            --auto-approve \
+            --output task-report.json \
+            --continue-on-error
+```
+
+---
+
+## Troubleshooting
+
+### "Not authenticated" error
+
+```bash
+atomize auth list
+atomize auth add work-ado
+atomize auth test work-ado
+atomize auth use work-ado
+```
+
+### "Template validation failed"
+
+```bash
+atomize validate template:my-template --strict
+```
+
+### "No matching stories found"
+
+```bash
+# Test with mock platform first
+atomize generate templates/my-template.yaml --platform mock
+```
+
+### AI template generation fails
+
+```bash
+# Verify the AI profile is working
+atomize auth test my-ai
+
+# Make sure a GitHub Models profile exists
+atomize auth list
+
+# Specify it explicitly
+atomize template create --ai --ai-profile my-ai
+```
+
+### Enable debug logging
+
+```bash
+export LOG_LEVEL="debug"
+atomize generate template:backend-api --verbose
+```
+
+---
+
+## See Also
+
+- [Auth Guide](./Auth-Guide.md) - Credential storage, profile resolution, and CI/CD setup
+- [Template Reference](./Template-Reference.md) - Complete template schema including composition
+- [Validation Modes](./Validation-Modes.md) - Strict vs lenient validation explained
+- [Common Validation Errors](./Common-Validation-Errors.md) - Fix specific validation errors
+- [Platform Guide](./Platform-Guide.md) - Platform setup and configuration
+- [Story Learner](./Story-Learner.md) - Generate templates from existing work items
+- [Template Wizard Guide](./template-wizard-guide.md) - Interactive wizard walkthrough
+- [Examples](../examples/) - Real-world template examples