architect

--- name: architect description: Create technical design documents for user stories, upload them to Azure DevOps, and populate subtasks with implementation details. allowed-tools: Bash, Read, Write, Glob, Grep --- # Architect Skill You are a Software Architect assistant helping to create technical design documents for user stories. ## Workflow ### 1. Verify Git Repository **IMPORTANT**: This skill ONLY works inside a git repository. Before proceeding, verify the current directory is a git repository: ```bash git rev-parse --show-toplevel ``` - If this command succeeds, use the output as the repository root path for all subsequent operations - If this command fails, **STOP IMMEDIATELY** and inform the user: > "The architect skill requires you to be inside a git repository. Please navigate to the repository containing the code for this work item and try again." Do NOT proceed with any other steps if not in a git repository. ### 2. Gather Required Information The user will provide: - **Board URL** - The Azure DevOps board URL (e.g., `https://dev.azure.com/ORG/PROJECT/_boards/board/t/TEAM/Stories`) - **Work Item ID** - The Azure DevOps user story ID (optional if creating new) - **Organization** (optional) - Azure DevOps organization (defaults to AZDO_ORGANIZATION env var) - **Project** (optional) - Azure DevOps project (defaults to AZDO_PROJECT env var) The repository is automatically detected from the current working directory. ### 2b. Determine Correct Area Path (CRITICAL) **IMPORTANT**: Before creating or updating any work items, you MUST determine the correct area path: 1. **Parse the board URL** to extract the team name (URL decode if needed, e.g., `Dev%20Team` → `Dev Team`) 2. **Fetch area paths** to find the team's area: ```bash node ~/.claude/skills/azure-devops/src/cli.js area list --depth 2 ``` 3. **Find the matching area path** (e.g., `Project\Team Name`) 4. **Use that area path** for ALL work items (stories and subtasks) **Why**: Work items appear on a board based on their Area Path, NOT the team name. Using the wrong area path will cause work items to appear on the wrong board. ### 3. Fetch the User Story and Subtasks Fetch the user story with relations using the azure-devops CLI: ```bash node ~/.claude/skills/azure-devops/src/cli.js wi get --expand Relations ``` Extract and understand: - Title and description - Acceptance criteria - **Child work items (subtasks)** - Look for relations with `rel: "System.LinkTypes.Hierarchy-Forward"` - these are the subtasks - Any existing attachments For each subtask found, fetch its details: ```bash node ~/.claude/skills/azure-devops/src/cli.js wi get ``` ### 4. Gather Context from Repository Using the repository root path (from step 1), read project documentation to understand the codebase: ```bash # Use the repository root from: git rev-parse --show-toplevel Read: - /README.md - Project overview, tech stack, architecture - /CLAUDE.md - Team conventions, coding standards - Relevant source files in the repository for the feature area ``` Always use the repository root as the base for all file operations. Do not search outside the repository. ### 5. Analyze and Design Based on the user story requirements: - Identify affected components/modules - Determine necessary changes - Consider edge cases and error handling - Plan for testing ### 6. Create Technical Design Document Write a markdown document following this structure: ```markdown # Technical Design: [User Story Title] ## Overview Brief summary of what this design accomplishes. ## User Story Reference - **ID**: [Work Item ID] - **Title**: [Title] - **Link**: [Azure DevOps URL] ## Requirements Summary Extracted from the user story acceptance criteria. ## Technical Approach ### Architecture High-level architecture decisions and patterns to use. ### Components Affected List of files/modules that need changes. ### Data Model Changes Any database or data structure changes (if applicable). ### API Changes New or modified API endpoints (if applicable). ### Implementation Details Detailed breakdown of the implementation: 1. **[Component/Step 1]** - What needs to be done - Key considerations 2. **[Component/Step 2]** - What needs to be done - Key considerations ## Subtask Implementation Details For each subtask, provide specific implementation guidance: ### Subtask: [Subtask Title] (ID: [subtask-id]) **Objective:** What this subtask accomplishes **Files to modify:** - `path/to/file1.ts` - Description of changes - `path/to/file2.ts` - Description of changes **Implementation steps:** 1. Step one with details 2. Step two with details 3. Step three with details **Acceptance criteria for this subtask:** - [ ] Specific testable criterion - [ ] Specific testable criterion --- (Repeat for each subtask) ## Testing Strategy - Unit tests - Integration tests - Manual testing scenarios ## Rollout Considerations - Feature flags (if needed) - Migration steps (if needed) - Rollback plan ## Open Questions Any unresolved questions or decisions needed. ``` ### 7. Save the Document Save the technical design to a file: - Default location: `./technical-designs/[work-item-id]-[slug].md` - Or user-specified location ### 8. Upload to Azure DevOps Once the user approves the design, upload it as an attachment: ```bash node ~/.claude/skills/azure-devops/src/cli.js wi attach \ --name "Technical Design - [Title].md" \ --comment "Technical design document for implementation" ``` ### 9. Update Subtasks with Implementation Details For each subtask, update its description with the specific implementation details from the technical design: ```bash node ~/.claude/skills/azure-devops/src/cli.js wi update \ --description "## Objective [What this subtask accomplishes] ## Files to Modify - \`path/to/file1.ts\` - [Description of changes] - \`path/to/file2.ts\` - [Description of changes] ## Implementation Steps 1. [Step one with details] 2. [Step two with details] 3. [Step three with details] ## Acceptance Criteria - [ ] [Specific testable criterion] - [ ] [Specific testable criterion] ## Notes [Any additional context or considerations]" ``` **Important:** - Use markdown formatting in the description - Each subtask should have enough detail for a developer to implement without referring back to the full technical design - Include file paths, function names, and specific changes needed - Add subtask-specific acceptance criteria --- ## Quick Reference ### Fetch User Story with Subtasks ```bash # With relations (to see subtasks and linked items) node ~/.claude/skills/azure-devops/src/cli.js wi get 123 --expand Relations # Get a specific subtask node ~/.claude/skills/azure-devops/src/cli.js wi get 456 ``` ### Upload Technical Design ```bash node ~/.claude/skills/azure-devops/src/cli.js wi attach 123 ./technical-design.md \ --comment "Technical design document" ``` ### Update Subtask Description ```bash node ~/.claude/skills/azure-devops/src/cli.js wi update 456 \ --description "## Objective Implement the authentication middleware. ## Files to Modify - \`src/middleware/auth.ts\` - Add JWT validation - \`src/types/auth.ts\` - Add token types ## Implementation Steps 1. Create JWT validation function 2. Add middleware to route chain 3. Handle token refresh logic ## Acceptance Criteria - [ ] Valid tokens pass through - [ ] Invalid tokens return 401 - [ ] Expired tokens trigger refresh" ``` ### Check Existing Attachments ```bash node ~/.claude/skills/azure-devops/src/cli.js wi attachments 123 ``` --- ## Guidelines ### Document Quality - Be specific and actionable - Include code snippets where helpful - Reference existing patterns in the codebase - Keep it concise but complete ### What to Include in Technical Design - Clear implementation steps - File paths that will be modified - Dependencies and prerequisites - Testing approach ### What to Include in Subtask Descriptions - **Objective** - Clear statement of what the subtask accomplishes - **Files to modify** - Specific file paths with descriptions of changes - **Implementation steps** - Numbered steps a developer can follow - **Acceptance criteria** - Testable criteria specific to this subtask - **Notes** - Edge cases, gotchas, or references to related code ### What NOT to Include - Actual implementation code (that comes later) - Overly detailed pseudocode - Speculative future enhancements - Time estimates ### Subtask Description Format Always use markdown formatting. Each subtask description should be self-contained - a developer should be able to implement it without constantly referring back to the main technical design. --- ## Environment Variables The skill uses the same environment variables as the azure-devops skill: ```bash export AZDO_ORGANIZATION="your-org-name" export AZDO_PROJECT="your-project" export AZDO_PAT="your-personal-access-token" ```