@sppg2001/atomize 1.2.4 → 2.0.0

package/docs/Platform-Guide.md

@@ -0,0 +1,662 @@
+# Platform Guide
+
+Setup and configuration guide for different work item management platforms.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Azure DevOps](#azure-devops)
+- [GitHub Models (AI)](#github-models-ai)
+- [Mock Platform](#mock-platform)
+- [Adding New Platforms](#adding-new-platforms)
+
+---
+
+## Overview
+
+Atomize connects to two kinds of external service — work item platforms (where tasks are created) and AI providers (for template generation). Each is configured as a named profile.
+
+**Work item platforms:**
+
+| Platform | Status | Features |
+|----------|--------|----------|
+| Azure DevOps | ✅ Production | Full support with WIQL queries |
+| Mock | ✅ Production | Testing and development |
+| Jira | 🚧 Planned | Coming soon |
+| GitHub Issues | 🚧 Planned | Coming soon |
+
+**AI providers:**
+
+| Provider | Status | Used for |
+|----------|--------|----------|
+| GitHub Models | ✅ Production | `template create --ai` |
+
+---
+
+## Azure DevOps
+
+Complete setup guide for Azure DevOps Services.
+
+### Prerequisites
+
+- Azure DevOps organization and project
+- Personal Access Token (PAT) with Work Items permissions
+- Node.js 18+ or Bun runtime
+
+### Quick Start
+
+1. **Get your organization URL and project name**
+
+   Your Azure DevOps URL looks like:
+   ```
+   https://dev.azure.com/{organization}
+   ```
+
+   Example: `https://dev.azure.com/contoso`
+
+2. **Create a Personal Access Token (PAT)**
+
+   - Go to `https://dev.azure.com/{organization}/_usersSettings/tokens`
+   - Click "New Token"
+   - Set scopes: **Work Items (Read, Write)**
+   - Copy the token (you won't see it again!)
+
+3. **Save a connection profile**
+
+   Interactive (recommended for local setup):
+   ```bash
+   atomize auth add work-ado
+   # Prompts for org URL, project, team, and PAT
+   # Set as default when prompted
+   ```
+
+   Non-interactive for CI/CD (use `--pat-stdin` to avoid token exposure in env vars):
+   ```bash
+   echo "$AZURE_DEVOPS_PAT" | atomize auth add ci \
+     --org-url https://dev.azure.com/myorg \
+     --project MyProject \
+     --team MyTeam \
+     --default \
+     --pat-stdin
+   ```
+
+4. **Test connection**
+
+   ```bash
+   atomize auth test work-ado
+   ```
+
+### Configuration
+
+Credentials are managed as named profiles using the `auth` commands. PATs are stored in the OS keychain when available. If the keychain is unavailable, `--insecure-storage` explicitly opts into an insecure local file fallback under `~/.atomize/`.
+
+**Add a profile:**
+```bash
+atomize auth add <name>
+```
+
+**Use a specific profile for generate:**
+```bash
+atomize generate template:backend-api --profile work-ado
+```
+
+**Set a profile as default (used when `--profile` is not specified):**
+```bash
+atomize auth use work-ado
+```
+
+**Select a profile via environment variable:**
+```bash
+export ATOMIZE_PROFILE=work-ado
+atomize generate template:backend-api
+```
+
+**Multiple profiles example:**
+```bash
+atomize auth add personal --org-url https://dev.azure.com/personal-org ...
+atomize auth add work     --org-url https://dev.azure.com/work-org ...
+
+atomize generate template.yaml --profile personal
+atomize generate template.yaml --profile work
+```
+
+### PAT Permissions
+
+Your Personal Access Token needs these scopes:
+
+| Scope | Access Level | Required |
+|-------|--------------|----------|
+| Work Items | Read | ✅ Yes |
+| Work Items | Write | ✅ Yes |
+| Project and Team | Read | ⚪ Optional |
+
+**Minimum permissions:**
+- Read work items
+- Write work items
+- Create work item links
+
+### Azure DevOps Concepts
+
+#### Work Item Types
+
+Default Azure DevOps work item types:
+
+```yaml
+filter:
+  workItemTypes:
+    - "User Story"           # Scrum
+    - "Product Backlog Item" # Agile
+    - "Bug"
+    - "Task"
+    - "Epic"
+    - "Feature"
+```
+
+#### States
+
+Common work item states:
+
+```yaml
+filter:
+  states:
+    - "New"        # Just created
+    - "Active"     # In progress
+    - "Resolved"   # Completed, awaiting verification
+    - "Closed"     # Verified and done
+    - "Removed"    # Cancelled
+```
+
+#### Area Paths
+
+Organize work items by product area:
+
+```yaml
+filter:
+  areaPaths:
+    - "MyProject\\Backend"
+    - "MyProject\\Frontend"
+    - "MyProject\\Infrastructure"
+```
+
+#### Iteration Paths
+
+Organize work items by sprint/iteration:
+
+```yaml
+filter:
+  iterations:
+    - "MyProject\\Sprint 23"
+    - "MyProject\\Sprint 24"
+```
+
+### WIQL Queries
+
+Azure DevOps uses Work Item Query Language (WIQL) for filtering.
+
+**Basic query structure:**
+```sql
+SELECT [System.Id] 
+FROM WorkItems 
+WHERE [System.TeamProject] = 'MyProject'
+  AND [System.WorkItemType] = 'User Story'
+  AND [System.State] = 'New'
+```
+
+**Template filter to WIQL:**
+
+Template:
+```yaml
+filter:
+  workItemTypes: ["User Story"]
+  states: ["New", "Active"]
+  tags:
+    include: ["backend"]
+```
+
+Generated WIQL:
+```sql
+SELECT [System.Id] 
+FROM WorkItems 
+WHERE [System.TeamProject] = 'MyProject'
+  AND [System.WorkItemType] IN ('User Story')
+  AND [System.State] IN ('New', 'Active')
+  AND [System.Tags] CONTAINS 'backend'
+```
+
+### Custom Fields
+
+Azure DevOps supports custom fields for work items.
+
+**Common custom fields:**
+
+```yaml
+filter:
+  customFields:
+    - field: "Custom.Team"
+      operator: "equals"
+      value: "Platform Engineering"
+    
+    - field: "Custom.Complexity"
+      operator: "greaterThan"
+      value: 3
+    
+    - field: "Microsoft.VSTS.Common.Priority"
+      operator: "lessThan"
+      value: 3
+```
+
+**Field reference format:**
+- System fields: `System.FieldName` (e.g., `System.State`)
+- Microsoft fields: `Microsoft.VSTS.*.FieldName`
+- Custom fields: `Custom.FieldName`
+
+**Common system fields:**
+- `System.Id` - Work item ID
+- `System.Title` - Title
+- `System.State` - Current state
+- `System.WorkItemType` - Type
+- `System.AssignedTo` - Assigned user
+- `System.Tags` - Tags (semicolon-separated)
+- `System.AreaPath` - Area path
+- `System.IterationPath` - Iteration path
+- `System.CreatedDate` - Creation date
+- `System.ChangedDate` - Last modified date
+
+**Common Microsoft fields:**
+- `Microsoft.VSTS.Scheduling.StoryPoints` - Story points
+- `Microsoft.VSTS.Scheduling.RemainingWork` - Remaining work (hours)
+- `Microsoft.VSTS.Common.Priority` - Priority (1-5)
+- `Microsoft.VSTS.Common.Activity` - Activity type
+- `Microsoft.VSTS.Common.BacklogPriority` - Backlog priority
+
+### Task Creation
+
+When creating tasks, Atomize sets these fields:
+
+```yaml
+# Task definition
+tasks:
+  - title: "Implement API"
+    description: "Implementation details"
+    estimationPercent: 40
+    tags: ["backend", "api"]
+    activity: "Development"
+    assignTo: "john@company.com"
+    priority: 2
+```
+
+Maps to Azure DevOps fields:
+- `System.Title` ← title
+- `System.Description` ← description
+- `Microsoft.VSTS.Scheduling.RemainingWork` ← estimationPercent * story points
+- `System.Tags` ← tags (joined with "; ")
+- `Microsoft.VSTS.Common.Activity` ← activity
+- `System.AssignedTo` ← assignTo
+- `Microsoft.VSTS.Common.Priority` ← priority
+
+### Troubleshooting
+
+#### Authentication Failures
+
+**Problem:** `Authentication failed: 401 Unauthorized`
+
+**Solutions:**
+1. Verify PAT hasn't expired — rotate it with `atomize auth rotate <name>`
+2. Check PAT has correct scopes (Work Items Read/Write)
+3. Verify organization URL format: `https://dev.azure.com/org`
+4. Don't include project in organization URL
+5. Test the profile: `atomize auth test <name>`
+
+#### No Work Items Found
+
+**Problem:** `Found 0 stories matching filter criteria`
+
+**Solutions:**
+1. Check work item types match your project's process template
+2. Verify states exist in your project
+3. Check area/iteration paths are correct (case-sensitive)
+4. Test with mock platform first:
+   ```bash
+   atomize generate template:backend-api --platform mock
+   ```
+
+#### Permission Errors
+
+**Problem:** `Failed to create task: Access Denied`
+
+**Solutions:**
+1. Verify PAT has Write permissions
+2. Check project permissions (Project Contributor role)
+3. Verify you can create work items manually in the web UI
+
+#### Connection Timeouts
+
+**Problem:** `Request timeout` or `ECONNRESET`
+
+**Solutions:**
+1. Check network connectivity
+2. Verify organization URL is accessible
+3. Check if behind corporate proxy (configure proxy settings)
+4. Try with increased timeout
+
+---
+
+## GitHub Models (AI)
+
+GitHub Models is the AI provider used by `template create --ai`. It is not a work item platform — no tasks are created through it — but it requires its own connection profile.
+
+### Prerequisites
+
+- A GitHub personal access token with the `models:read` scope
+  - Create one at `https://github.com/settings/tokens`
+
+### Setup
+
+```bash
+atomize auth add my-ai
+# → select "GitHub Models (AI template generation)" when prompted for platform type
+# → enter your GitHub PAT
+
+atomize auth test my-ai
+```
+
+### Usage
+
+Once the profile is saved, pass it when generating AI templates:
+
+```bash
+atomize template create --ai                        # uses default GitHub Models profile
+atomize template create --ai --ai-profile my-ai     # explicit profile
+atomize template create --ai --ground --profile work-ado  # grounded with ADO context
+```
+
+`ATOMIZE_AI_PROFILE` can be set as an alternative to `--ai-profile`.
+
+See [Template Creation Wizard — AI-Assisted Generation](./template-wizard-guide.md#ai-assisted-generation) for the full workflow.
+
+---
+
+## Mock Platform
+
+The mock platform provides sample data for testing and development.
+
+### Usage
+
+```bash
+atomize generate template:backend-api --platform mock
+```
+
+### Features
+
+- No configuration required
+- Sample user stories with various states and tags
+- Simulated network delays
+- Perfect for template development and testing
+
+### Sample Data
+
+The mock platform includes 7 sample stories:
+
+```
+STORY-001: Implement user authentication API
+  State: New, Tags: backend, api, security
+  Estimation: 8 points
+
+STORY-002: Create user profile dashboard
+  State: Active, Tags: frontend, react, ui
+  Estimation: 5 points
+
+STORY-003: Implement payment processing
+  State: New, Tags: backend, api, payment
+  Estimation: 13 points
+
+STORY-004: Add search functionality
+  State: Approved, Tags: fullstack, search, api, frontend
+  Estimation: 8 points
+
+STORY-005: Optimize database queries
+  State: New, Tags: backend, database, performance
+  Estimation: 3 points
+
+STORY-006: Mobile responsive design
+  State: New, Tags: frontend, mobile, css
+  Estimation: 5 points
+
+STORY-007: Implement data export feature
+  State: Active, Tags: backend, api, export
+  Estimation: 8 points (has 1 existing task)
+```
+
+### Testing Workflows
+
+**1. Template Development:**
+```bash
+# Create template
+atomize template create --scratch --save-as test-template
+
+# Test with mock data
+atomize generate test-template.yaml --platform mock
+
+# Iterate until satisfied
+```
+
+**2. Filter Testing:**
+```bash
+# Test different filters
+atomize generate test-template.yaml --platform mock
+
+# Check which stories match
+# Adjust filter criteria
+# Repeat
+```
+
+**3. CI/CD Testing:**
+```yaml
+# .github/workflows/test.yml
+- name: Test Templates
+  run: |
+    for template in templates/*.yaml; do
+      atomize validate "$template"
+      atomize generate "$template" --platform mock
+    done
+```
+
+---
+
+## Adding New Platforms
+
+Want to add support for Jira, GitHub, or another platform? Here's how.
+
+### Architecture
+
+All platforms implement the `IPlatformAdapter` interface:
+
+```typescript
+interface IPlatformAdapter {
+  authenticate(config?: AuthConfig): Promise<void>;
+  queryWorkItems(filter: FilterCriteria): Promise<WorkItem[]>;
+  createTask(parentId: string, task: TaskDefinition): Promise<WorkItem>;
+  createTasksBulk(parentId: string, tasks: TaskDefinition[]): Promise<WorkItem[]>;
+  getPlatformMetadata(): PlatformMetadata;
+  
+  // Optional methods
+  getWorkItem?(id: string): Promise<WorkItem | null>;
+  testConnection?(): Promise<boolean>;
+  getChildren?(parentId: string): Promise<WorkItem[]>;
+  updateWorkItem?(id: string, updates: Partial<WorkItem>): Promise<WorkItem>;
+  deleteWorkItem?(id: string): Promise<boolean>;
+}
+```
+
+### Steps to Add a Platform
+
+#### 1. Create Adapter Class
+
+```typescript
+// src/platforms/adapters/jira/jira.adapter.ts
+import { IPlatformAdapter } from "@platforms/interfaces/platform.interface";
+
+export interface JiraConfig extends PlatformConfig {
+  baseUrl: string;
+  email: string;
+  apiToken: string;
+  projectKey: string;
+}
+
+export class JiraAdapter implements IPlatformAdapter {
+  constructor(private config: JiraConfig) {}
+  
+  async authenticate(config?: AuthConfig): Promise<void> {
+    // Implement authentication
+  }
+  
+  async queryWorkItems(filter: FilterCriteria): Promise<WorkItem[]> {
+    // Convert filter to JQL
+    // Query Jira API
+    // Convert results to WorkItem[]
+  }
+  
+  async createTask(parentId: string, task: TaskDefinition): Promise<WorkItem> {
+    // Create subtask in Jira
+  }
+  
+  // ... implement other methods
+}
+```
+
+#### 2. Add to Platform Factory
+
+```typescript
+// src/platforms/platform-factory.ts
+import { JiraAdapter } from "./adapters/jira/jira.adapter";
+
+export class PlatformFactory {
+  static create(type: PlatformType, config?: PlatformConfig): IPlatformAdapter {
+    switch (type) {
+      case "jira":
+        return new JiraAdapter(config as JiraConfig);
+      // ... other cases
+    }
+  }
+}
+```
+
+#### 3. Add Configuration Helper
+
+```typescript
+// src/config/jira.config.ts
+export async function getJiraConfigInteractive(): Promise<JiraConfig> {
+  const answers = await inquirer.prompt([
+    {
+      type: "input",
+      name: "baseUrl",
+      message: "Jira base URL (e.g., https://yourcompany.atlassian.net):",
+    },
+    {
+      type: "input",
+      name: "email",
+      message: "Email:",
+    },
+    {
+      type: "password",
+      name: "apiToken",
+      message: "API Token:",
+    },
+    {
+      type: "input",
+      name: "projectKey",
+      message: "Project key:",
+    },
+  ]);
+  
+  return {
+    type: "jira",
+    ...answers,
+  };
+}
+```
+
+#### 4. Update Types
+
+```typescript
+// src/platforms/interfaces/platform.interface.ts
+export type PlatformType = 
+  | "mock" 
+  | "azure-devops" 
+  | "jira"        // Add new type
+  | "github";
+```
+
+#### 5. Write Tests
+
+```typescript
+// src/platforms/adapters/jira/jira.test.ts
+describe("JiraAdapter", () => {
+  test("should authenticate with valid credentials", async () => {
+    // Test implementation
+  });
+  
+  test("should query issues with JQL", async () => {
+    // Test implementation
+  });
+  
+  // More tests...
+});
+```
+
+#### 6. Add Documentation
+
+Update this guide with:
+- Setup instructions
+- Configuration options
+- Field mappings
+- Examples
+- Troubleshooting
+
+### Field Mapping
+
+Each platform has different field names. Map them to the common `WorkItem` interface:
+
+```typescript
+private convertToWorkItem(jiraIssue: JiraIssue): WorkItem {
+  return {
+    id: jiraIssue.key,                    // PROJ-123
+    title: jiraIssue.fields.summary,
+    type: this.mapIssueType(jiraIssue.fields.issuetype.name),
+    state: jiraIssue.fields.status.name,
+    assignedTo: jiraIssue.fields.assignee?.emailAddress,
+    estimation: jiraIssue.fields.customfield_10016, // Story points
+    tags: jiraIssue.fields.labels,
+    description: jiraIssue.fields.description,
+    priority: this.mapPriority(jiraIssue.fields.priority.name),
+    platformSpecific: jiraIssue,          // Keep original data
+  };
+}
+```
+
+### Contributing
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines on submitting new platform adapters.
+
+---
+
+## Platform Comparison
+
+| Feature | Azure DevOps | Mock | Jira | GitHub |
+|---------|--------------|------|------|--------|
+| Authentication | PAT | None | API Token | PAT |
+| Work Items | ✅ | ✅ | 🚧 | 🚧 |
+| Custom Fields | ✅ | ✅ | 🚧 | 🚧 |
+| Bulk Creation | ✅ | ✅ | 🚧 | 🚧 |
+| Work Item Links | ✅ | ✅ | 🚧 | 🚧 |
+| Query Language | WIQL | Simple | JQL | - |
+| Real-time | ✅ | ✅ | 🚧 | 🚧 |
+
+---
+
+## See Also
+
+- [Auth Guide](./Auth-Guide.md) - Credential storage, profile resolution, and CI/CD setup
+- [CLI Reference](./Cli-Reference.md) - Command-line usage
+- [Template Reference](./Template-Reference.md) - Template schema
+- [Examples](../examples/) - Real-world examples