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:

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:

   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:

node ~/.claude/skills/azure-devops/src/cli.js wi get <id> --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:

node ~/.claude/skills/azure-devops/src/cli.js wi get <subtask-id>

4. Gather Context from Repository

Using the repository root path (from step 1), read project documentation to understand the codebase:

# Use the repository root from: git rev-parse --show-toplevel

Read:
- <repo-root>/README.md - Project overview, tech stack, architecture
- <repo-root>/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:

# 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)


 Unit tests
 Integration tests
 Manual testing scenarios


 Feature flags (if needed)
 Migration steps (if needed)
 Rollback plan


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:

node ~/.claude/skills/azure-devops/src/cli.js wi attach <id> <file-path> \
  --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:

node ~/.claude/skills/azure-devops/src/cli.js wi update <subtask-id> \
  --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

# 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

node ~/.claude/skills/azure-devops/src/cli.js wi attach 123 ./technical-design.md \
  --comment "Technical design document"

Update Subtask Description

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

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:

export AZDO_ORGANIZATION="your-org-name"
export AZDO_PROJECT="your-project"
export AZDO_PAT="your-personal-access-token"