workspace-architect 1.3.0

package/assets/instructions/angular.instructions.md

@@ -0,0 +1,104 @@
+---
+description: 'Angular-specific coding standards and best practices'
+applyTo: '**/*.ts, **/*.html, **/*.scss, **/*.css'
+---
+
+# Angular Development Instructions
+
+Instructions for generating high-quality Angular applications with TypeScript, using Angular Signals for state management, adhering to Angular best practices as outlined at https://angular.dev.
+
+## Project Context
+- Latest Angular version (use standalone components by default)
+- TypeScript for type safety
+- Angular CLI for project setup and scaffolding
+- Follow Angular Style Guide (https://angular.dev/style-guide)
+- Use Angular Material or other modern UI libraries for consistent styling (if specified)
+
+## Development Standards
+
+### Architecture
+- Use standalone components unless modules are explicitly required
+- Organize code by standalone feature modules or domains for scalability
+- Implement lazy loading for feature modules to optimize performance
+- Use Angular's built-in dependency injection system effectively
+- Structure components with a clear separation of concerns (smart vs. presentational components)
+
+### TypeScript
+- Enable strict mode in `tsconfig.json` for type safety
+- Define clear interfaces and types for components, services, and models
+- Use type guards and union types for robust type checking
+- Implement proper error handling with RxJS operators (e.g., `catchError`)
+- Use typed forms (e.g., `FormGroup`, `FormControl`) for reactive forms
+
+### Component Design
+- Follow Angular's component lifecycle hooks best practices
+- When using Angular >= 19, Use `input()` `output()`, `viewChild()`, `viewChildren()`, `contentChild()` and `contentChildren()` functions instead of decorators; otherwise use decorators
+- Leverage Angular's change detection strategy (default or `OnPush` for performance)
+- Keep templates clean and logic in component classes or services
+- Use Angular directives and pipes for reusable functionality
+
+### Styling
+- Use Angular's component-level CSS encapsulation (default: ViewEncapsulation.Emulated)
+- Prefer SCSS for styling with consistent theming
+- Implement responsive design using CSS Grid, Flexbox, or Angular CDK Layout utilities
+- Follow Angular Material's theming guidelines if used
+- Maintain accessibility (a11y) with ARIA attributes and semantic HTML
+
+### State Management
+- Use Angular Signals for reactive state management in components and services
+- Leverage `signal()`, `computed()`, and `effect()` for reactive state updates
+- Use writable signals for mutable state and computed signals for derived state
+- Handle loading and error states with signals and proper UI feedback
+- Use Angular's `AsyncPipe` to handle observables in templates when combining signals with RxJS
+
+### Data Fetching
+- Use Angular's `HttpClient` for API calls with proper typing
+- Implement RxJS operators for data transformation and error handling
+- Use Angular's `inject()` function for dependency injection in standalone components
+- Implement caching strategies (e.g., `shareReplay` for observables)
+- Store API response data in signals for reactive updates
+- Handle API errors with global interceptors for consistent error handling
+
+### Security
+- Sanitize user inputs using Angular's built-in sanitization
+- Implement route guards for authentication and authorization
+- Use Angular's `HttpInterceptor` for CSRF protection and API authentication headers
+- Validate form inputs with Angular's reactive forms and custom validators
+- Follow Angular's security best practices (e.g., avoid direct DOM manipulation)
+
+### Performance
+- Enable production builds with `ng build --prod` for optimization
+- Use lazy loading for routes to reduce initial bundle size
+- Optimize change detection with `OnPush` strategy and signals for fine-grained reactivity
+- Use trackBy in `ngFor` loops to improve rendering performance
+- Implement server-side rendering (SSR) or static site generation (SSG) with Angular Universal (if specified)
+
+### Testing
+- Write unit tests for components, services, and pipes using Jasmine and Karma
+- Use Angular's `TestBed` for component testing with mocked dependencies
+- Test signal-based state updates using Angular's testing utilities
+- Write end-to-end tests with Cypress or Playwright (if specified)
+- Mock HTTP requests using `provideHttpClientTesting`
+- Ensure high test coverage for critical functionality
+
+## Implementation Process
+1. Plan project structure and feature modules
+2. Define TypeScript interfaces and models
+3. Scaffold components, services, and pipes using Angular CLI
+4. Implement data services and API integrations with signal-based state
+5. Build reusable components with clear inputs and outputs
+6. Add reactive forms and validation
+7. Apply styling with SCSS and responsive design
+8. Implement lazy-loaded routes and guards
+9. Add error handling and loading states using signals
+10. Write unit and end-to-end tests
+11. Optimize performance and bundle size
+
+## Additional Guidelines
+- Follow the Angular Style Guide for file naming conventions (see https://angular.dev/style-guide), e.g., use `feature.ts` for components and `feature-service.ts` for services. For legacy codebases, maintain consistency with existing pattern.
+- Use Angular CLI commands for generating boilerplate code
+- Document components and services with clear JSDoc comments
+- Ensure accessibility compliance (WCAG 2.1) where applicable
+- Use Angular's built-in i18n for internationalization (if specified)
+- Keep code DRY by creating reusable utilities and shared modules
+- Use signals consistently for state management to ensure reactive updates

package/assets/instructions/ansible.instructions.md

@@ -0,0 +1,88 @@
+---
+description: 'Ansible conventions and best practices'
+applyTo: '**/*.yaml, **/*.yml'
+---
+
+# Ansible Conventions and Best Practices
+
+## General Instructions
+
+- Use Ansible to configure and manage infrastructure.
+- Use version control for your Ansible configurations.
+- Keep things simple; only use advanced features when necessary
+- Give every play, block, and task a concise but descriptive `name`
+  - Start names with an action verb that indicates the operation being performed, such as "Install," "Configure," or "Copy"
+  - Capitalize the first letter of the task name
+  - Omit periods from the end of task names for brevity
+  - Omit the role name from role tasks; Ansible will automatically display the role name when running a role
+  - When including tasks from a separate file, you may include the filename in each task name to make tasks easier to locate (e.g., `<TASK_FILENAME> : <TASK_NAME>`)
+- Use comments to provide additional context about **what**, **how**, and/or **why** something is being done
+  - Don't include redundant comments
+- Use dynamic inventory for cloud resources
+  - Use tags to dynamically create groups based on environment, function, location, etc.
+  - Use `group_vars` to set variables based on these attributes
+- Use idempotent Ansible modules whenever possible; avoid `shell`, `command`, and `raw`, as they break idempotency
+  - If you have to use `shell` or `command`, use the `creates:` or `removes:` parameter, where feasible, to prevent unnecessary execution
+- Use [fully qualified collection names (FQCN)](https://docs.ansible.com/ansible/latest/reference_appendices/glossary.html#term-Fully-Qualified-Collection-Name-FQCN) to ensure the correct module or plugin is selected
+  - Use the `ansible.builtin` collection for [builtin modules and plugins](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/index.html#plugin-index)
+- Group related tasks together to improve readability and modularity
+- For modules where `state` is optional, explicitly set `state: present` or `state: absent` to improve clarity and consistency
+- Use the lowest privileges necessary to perform a task
+  - Only set `become: true` at the play level or on an `include:` statement, if all included tasks require super user privileges; otherwise, specify `become: true` at the task level
+  - Only set `become: true` on a task if it requires super user privileges
+
+## Secret Management
+
+- When using Ansible alone, store secrets using Ansible Vault
+  - Use the following process to make it easy to find where vaulted variables are defined
+    1. Create a `group_vars/` subdirectory named after the group
+    2. Inside this subdirectory, create two files named `vars` and `vault`
+    3. In the `vars` file, define all of the variables needed, including any sensitive ones
+    4. Copy all of the sensitive variables over to the `vault` file and prefix these variables with `vault_`
+    5. Adjust the variables in the `vars` file to point to the matching `vault_` variables using Jinja2 syntax: `db_password: "{{ vault_db_password }}"`
+    6. Encrypt the `vault` file to protect its contents
+    7. Use the variable name from the `vars` file in your playbooks
+- When using other tools with Ansible (e.g., Terraform), store secrets in a third-party secrets management tool (e.g., Hashicorp Vault, AWS Secrets Manager, etc.)
+  - This allows all tools to reference a single source of truth for secrets and prevents configurations from getting out of sync
+
+## Style
+
+- Use 2-space indentation and always indent lists
+- Separate each of the following with a single blank line:
+  - Two host blocks
+  - Two task blocks
+  - Host and include blocks
+- Use `snake_case` for variable names
+- Sort variables alphabetically when defining them in `vars:` maps or variable files
+- Always use multi-line map syntax, regardless of how many pairs exist in the map
+  - It improves readability and reduces changeset collisions for version control
+- Prefer single quotes over double quotes
+  - The only time you should use double quotes is when they are nested within single quotes (e.g. Jinja map reference), or when your string requires escaping characters (e.g., using "\n" to represent a newline)
+  - If you must write a long string, use folded block scalar syntax (i.e., `>`) to replace newlines with spaces or literal block scalar syntax (i.e., `|`) to preserve newlines; omit all special quoting
+- The `host` section of a play should follow this general order:
+  - `hosts` declaration
+  - Host options in alphabetical order (e.g., `become`, `remote_user`, `vars`)
+  - `pre_tasks`
+  - `roles`
+  - `tasks`
+- Each task should follow this general order:
+  - `name`
+  - Task declaration (e.g., `service:`, `package:`)
+  - Task parameters (using multi-line map syntax)
+  - Loop operators (e.g., `loop`)
+  - Task options in alphabetical order (e.g. `become`, `ignore_errors`, `register`)
+  - `tags`
+- For `include` statements, quote filenames and only use blank lines between `include` statements if they are multi-line (e.g., they have tags)
+
+## Linting
+
+- Use `ansible-lint` and `yamllint` to check syntax and enforce project standards
+- Use `ansible-playbook --syntax-check` to check for syntax errors
+- Use `ansible-playbook --check --diff` to perform a dry-run of playbook execution
+
+<!-- 
+These guidelines were based on, or copied from, the following sources:
+
+- [Ansible Documentation - Tips and Tricks](https://docs.ansible.com/ansible/latest/tips_tricks/index.html)
+- [Whitecloud Ansible Styleguide](https://github.com/whitecloud/ansible-styleguide)
+-->

package/assets/instructions/aspnet-rest-apis.instructions.md

@@ -0,0 +1,110 @@
+---
+description: 'Guidelines for building REST APIs with ASP.NET'
+applyTo: '**/*.cs, **/*.json'
+---
+
+# ASP.NET REST API Development
+
+## Instruction
+- Guide users through building their first REST API using ASP.NET Core 9.
+- Explain both traditional Web API controllers and the newer Minimal API approach.
+- Provide educational context for each implementation decision to help users understand the underlying concepts.
+- Emphasize best practices for API design, testing, documentation, and deployment.
+- Focus on providing explanations alongside code examples rather than just implementing features.
+
+## API Design Fundamentals
+
+- Explain REST architectural principles and how they apply to ASP.NET Core APIs.
+- Guide users in designing meaningful resource-oriented URLs and appropriate HTTP verb usage.
+- Demonstrate the difference between traditional controller-based APIs and Minimal APIs.
+- Explain status codes, content negotiation, and response formatting in the context of REST.
+- Help users understand when to choose Controllers vs. Minimal APIs based on project requirements.
+
+## Project Setup and Structure
+
+- Guide users through creating a new ASP.NET Core 9 Web API project with the appropriate templates.
+- Explain the purpose of each generated file and folder to build understanding of the project structure.
+- Demonstrate how to organize code using feature folders or domain-driven design principles.
+- Show proper separation of concerns with models, services, and data access layers.
+- Explain the Program.cs and configuration system in ASP.NET Core 9 including environment-specific settings.
+
+## Building Controller-Based APIs
+
+- Guide the creation of RESTful controllers with proper resource naming and HTTP verb implementation.
+- Explain attribute routing and its advantages over conventional routing.
+- Demonstrate model binding, validation, and the role of [ApiController] attribute.
+- Show how dependency injection works within controllers.
+- Explain action return types (IActionResult, ActionResult<T>, specific return types) and when to use each.
+
+## Implementing Minimal APIs
+
+- Guide users through implementing the same endpoints using the Minimal API syntax.
+- Explain the endpoint routing system and how to organize route groups.
+- Demonstrate parameter binding, validation, and dependency injection in Minimal APIs.
+- Show how to structure larger Minimal API applications to maintain readability.
+- Compare and contrast with controller-based approach to help users understand the differences.
+
+## Data Access Patterns
+
+- Guide the implementation of a data access layer using Entity Framework Core.
+- Explain different options (SQL Server, SQLite, In-Memory) for development and production.
+- Demonstrate repository pattern implementation and when it's beneficial.
+- Show how to implement database migrations and data seeding.
+- Explain efficient query patterns to avoid common performance issues.
+
+## Authentication and Authorization
+
+- Guide users through implementing authentication using JWT Bearer tokens.
+- Explain OAuth 2.0 and OpenID Connect concepts as they relate to ASP.NET Core.
+- Show how to implement role-based and policy-based authorization.
+- Demonstrate integration with Microsoft Entra ID (formerly Azure AD).
+- Explain how to secure both controller-based and Minimal APIs consistently.
+
+## Validation and Error Handling
+
+- Guide the implementation of model validation using data annotations and FluentValidation.
+- Explain the validation pipeline and how to customize validation responses.
+- Demonstrate a global exception handling strategy using middleware.
+- Show how to create consistent error responses across the API.
+- Explain problem details (RFC 7807) implementation for standardized error responses.
+
+## API Versioning and Documentation
+
+- Guide users through implementing and explaining API versioning strategies.
+- Demonstrate Swagger/OpenAPI implementation with proper documentation.
+- Show how to document endpoints, parameters, responses, and authentication.
+- Explain versioning in both controller-based and Minimal APIs.
+- Guide users on creating meaningful API documentation that helps consumers.
+
+## Logging and Monitoring
+
+- Guide the implementation of structured logging using Serilog or other providers.
+- Explain the logging levels and when to use each.
+- Demonstrate integration with Application Insights for telemetry collection.
+- Show how to implement custom telemetry and correlation IDs for request tracking.
+- Explain how to monitor API performance, errors, and usage patterns.
+
+## Testing REST APIs
+
+- Guide users through creating unit tests for controllers, Minimal API endpoints, and services.
+- Explain integration testing approaches for API endpoints.
+- Demonstrate how to mock dependencies for effective testing.
+- Show how to test authentication and authorization logic.
+- Explain test-driven development principles as applied to API development.
+
+## Performance Optimization
+
+- Guide users on implementing caching strategies (in-memory, distributed, response caching).
+- Explain asynchronous programming patterns and why they matter for API performance.
+- Demonstrate pagination, filtering, and sorting for large data sets.
+- Show how to implement compression and other performance optimizations.
+- Explain how to measure and benchmark API performance.
+
+## Deployment and DevOps
+
+- Guide users through containerizing their API using .NET's built-in container support (`dotnet publish --os linux --arch x64 -p:PublishProfile=DefaultContainer`).
+- Explain the differences between manual Dockerfile creation and .NET's container publishing features.
+- Explain CI/CD pipelines for ASP.NET Core applications.
+- Demonstrate deployment to Azure App Service, Azure Container Apps, or other hosting options.
+- Show how to implement health checks and readiness probes.
+- Explain environment-specific configurations for different deployment stages.

package/assets/instructions/astro.instructions.md

@@ -0,0 +1,182 @@
+---
+description: 'Astro development standards and best practices for content-driven websites'
+applyTo: '**/*.astro, **/*.ts, **/*.js, **/*.md, **/*.mdx'
+---
+
+# Astro Development Instructions
+
+Instructions for building high-quality Astro applications following the content-driven, server-first architecture with modern best practices.
+
+## Project Context
+- Astro 5.x with Islands Architecture and Content Layer API
+- TypeScript for type safety and better DX with auto-generated types
+- Content-driven websites (blogs, marketing, e-commerce, documentation)
+- Server-first rendering with selective client-side hydration
+- Support for multiple UI frameworks (React, Vue, Svelte, Solid, etc.)
+- Static site generation (SSG) by default with optional server-side rendering (SSR)
+- Enhanced performance with modern content loading and build optimizations
+
+## Development Standards
+
+### Architecture
+- Embrace the Islands Architecture: server-render by default, hydrate selectively
+- Organize content with Content Collections for type-safe Markdown/MDX management
+- Structure projects by feature or content type for scalability
+- Use component-based architecture with clear separation of concerns
+- Implement progressive enhancement patterns
+- Follow Multi-Page App (MPA) approach over Single-Page App (SPA) patterns
+
+### TypeScript Integration
+- Configure `tsconfig.json` with recommended v5.0 settings:
+```json
+{
+  "extends": "astro/tsconfigs/base",
+  "include": [".astro/types.d.ts", "**/*"],
+  "exclude": ["dist"]
+}
+```
+- Types auto-generated in `.astro/types.d.ts` (replaces `src/env.d.ts`)
+- Run `astro sync` to generate/update type definitions
+- Define component props with TypeScript interfaces
+- Leverage auto-generated types for content collections and Content Layer API
+
+### Component Design
+- Use `.astro` components for static, server-rendered content
+- Import framework components (React, Vue, Svelte) only when interactivity is needed
+- Follow Astro's component script structure: frontmatter at top, template below
+- Use meaningful component names following PascalCase convention
+- Keep components focused and composable
+- Implement proper prop validation and default values
+
+### Content Collections
+
+#### Modern Content Layer API (v5.0+)
+- Define collections in `src/content.config.ts` using the new Content Layer API
+- Use built-in loaders: `glob()` for file-based content, `file()` for single files
+- Leverage enhanced performance and scalability with the new loading system
+- Example with Content Layer API:
+```typescript
+import { defineCollection, z } from 'astro:content';
+import { glob } from 'astro/loaders';
+
+const blog = defineCollection({
+  loader: glob({ pattern: '**/*.md', base: './src/content/blog' }),
+  schema: z.object({
+    title: z.string(),
+    pubDate: z.date(),
+    tags: z.array(z.string()).optional()
+  })
+});
+```
+
+#### Legacy Collections (backward compatible)
+- Legacy `type: 'content'` collections still supported via automatic glob() implementation
+- Migrate existing collections by adding explicit `loader` configuration
+- Use type-safe queries with `getCollection()` and `getEntry()`
+- Structure content with frontmatter validation and auto-generated types
+
+### View Transitions & Client-Side Routing
+- Enable with `<ClientRouter />` component in layout head (renamed from `<ViewTransitions />` in v5.0)
+- Import from `astro:transitions`: `import { ClientRouter } from 'astro:transitions'`
+- Provides SPA-like navigation without full page reloads
+- Customize transition animations with CSS and view-transition-name
+- Maintain state across page navigations with persistent islands
+- Use `transition:persist` directive to preserve component state
+
+### Performance Optimization
+- Default to zero JavaScript - only add interactivity where needed
+- Use client directives strategically (`client:load`, `client:idle`, `client:visible`)
+- Implement lazy loading for images and components
+- Optimize static assets with Astro's built-in optimization
+- Leverage Content Layer API for faster content loading and builds
+- Minimize bundle size by avoiding unnecessary client-side JavaScript
+
+### Styling
+- Use scoped styles in `.astro` components by default
+- Implement CSS preprocessing (Sass, Less) when needed
+- Use CSS custom properties for theming and design systems
+- Follow mobile-first responsive design principles
+- Ensure accessibility with semantic HTML and proper ARIA attributes
+- Consider utility-first frameworks (Tailwind CSS) for rapid development
+
+### Client-Side Interactivity
+- Use framework components (React, Vue, Svelte) for interactive elements
+- Choose the right hydration strategy based on user interaction patterns
+- Implement state management within framework boundaries
+- Handle client-side routing carefully to maintain MPA benefits
+- Use Web Components for framework-agnostic interactivity
+- Share state between islands using stores or custom events
+
+### API Routes and SSR
+- Create API routes in `src/pages/api/` for dynamic functionality
+- Use proper HTTP methods and status codes
+- Implement request validation and error handling
+- Enable SSR mode for dynamic content requirements
+- Use middleware for authentication and request processing
+- Handle environment variables securely
+
+### SEO and Meta Management
+- Use Astro's built-in SEO components and meta tag management
+- Implement proper Open Graph and Twitter Card metadata
+- Generate sitemaps automatically for better search indexing
+- Use semantic HTML structure for better accessibility and SEO
+- Implement structured data (JSON-LD) for rich snippets
+- Optimize page titles and descriptions for search engines
+
+### Image Optimization
+- Use Astro's `<Image />` component for automatic optimization
+- Implement responsive images with proper srcset generation
+- Use WebP and AVIF formats for modern browsers
+- Lazy load images below the fold
+- Provide proper alt text for accessibility
+- Optimize images at build time for better performance
+
+### Data Fetching
+- Fetch data at build time in component frontmatter
+- Use dynamic imports for conditional data loading
+- Implement proper error handling for external API calls
+- Cache expensive operations during build process
+- Use Astro's built-in fetch with automatic TypeScript inference
+- Handle loading states and fallbacks appropriately
+
+### Build & Deployment
+- Optimize static assets with Astro's built-in optimizations
+- Configure deployment for static (SSG) or hybrid (SSR) rendering
+- Use environment variables for configuration management
+- Enable compression and caching for production builds
+
+## Key Astro v5.0 Updates
+
+### Breaking Changes
+- **ClientRouter**: Use `<ClientRouter />` instead of `<ViewTransitions />`
+- **TypeScript**: Auto-generated types in `.astro/types.d.ts` (run `astro sync`)
+- **Content Layer API**: New `glob()` and `file()` loaders for enhanced performance
+
+### Migration Example
+```typescript
+// Modern Content Layer API
+import { defineCollection, z } from 'astro:content';
+import { glob } from 'astro/loaders';
+
+const blog = defineCollection({
+  loader: glob({ pattern: '**/*.md', base: './src/content/blog' }),
+  schema: z.object({ title: z.string(), pubDate: z.date() })
+});
+```
+
+## Implementation Guidelines
+
+### Development Workflow
+1. Use `npm create astro@latest` with TypeScript template
+2. Configure Content Layer API with appropriate loaders
+3. Set up TypeScript with `astro sync` for type generation
+4. Create layout components with Islands Architecture
+5. Implement content pages with SEO and performance optimization
+
+### Astro-Specific Best Practices
+- **Islands Architecture**: Server-first with selective hydration using client directives
+- **Content Layer API**: Use `glob()` and `file()` loaders for scalable content management
+- **Zero JavaScript**: Default to static rendering, add interactivity only when needed
+- **View Transitions**: Enable SPA-like navigation with `<ClientRouter />`
+- **Type Safety**: Leverage auto-generated types from Content Collections
+- **Performance**: Optimize with built-in image optimization and minimal client bundles

package/assets/instructions/azure-devops-pipelines.instructions.md

@@ -0,0 +1,185 @@
+---
+description: 'Best practices for Azure DevOps Pipeline YAML files'
+applyTo: '**/azure-pipelines.yml, **/azure-pipelines*.yml, **/*.pipeline.yml'
+---
+
+# Azure DevOps Pipeline YAML Best Practices
+
+## General Guidelines
+
+- Use YAML syntax consistently with proper indentation (2 spaces)
+- Always include meaningful names and display names for pipelines, stages, jobs, and steps
+- Implement proper error handling and conditional execution
+- Use variables and parameters to make pipelines reusable and maintainable
+- Follow the principle of least privilege for service connections and permissions
+- Include comprehensive logging and diagnostics for troubleshooting
+
+## Pipeline Structure
+
+- Organize complex pipelines using stages for better visualization and control
+- Use jobs to group related steps and enable parallel execution when possible
+- Implement proper dependencies between stages and jobs
+- Use templates for reusable pipeline components
+- Keep pipeline files focused and modular - split large pipelines into multiple files
+
+## Build Best Practices
+
+- Use specific agent pool versions and VM images for consistency
+- Cache dependencies (npm, NuGet, Maven, etc.) to improve build performance
+- Implement proper artifact management with meaningful names and retention policies
+- Use build variables for version numbers and build metadata
+- Include code quality gates (linting, testing, security scans)
+- Ensure builds are reproducible and environment-independent
+
+## Testing Integration
+
+- Run unit tests as part of the build process
+- Publish test results in standard formats (JUnit, VSTest, etc.)
+- Include code coverage reporting and quality gates
+- Implement integration and end-to-end tests in appropriate stages
+- Use test impact analysis when available to optimize test execution
+- Fail fast on test failures to provide quick feedback
+
+## Security Considerations
+
+- Use Azure Key Vault for sensitive configuration and secrets
+- Implement proper secret management with variable groups
+- Use service connections with minimal required permissions
+- Enable security scans (dependency vulnerabilities, static analysis)
+- Implement approval gates for production deployments
+- Use managed identities when possible instead of service principals
+
+## Deployment Strategies
+
+- Implement proper environment promotion (dev → staging → production)
+- Use deployment jobs with proper environment targeting
+- Implement blue-green or canary deployment strategies when appropriate
+- Include rollback mechanisms and health checks
+- Use infrastructure as code (ARM, Bicep, Terraform) for consistent deployments
+- Implement proper configuration management per environment
+
+## Variable and Parameter Management
+
+- Use variable groups for shared configuration across pipelines
+- Implement runtime parameters for flexible pipeline execution
+- Use conditional variables based on branches or environments
+- Secure sensitive variables and mark them as secrets
+- Document variable purposes and expected values
+- Use variable templates for complex variable logic
+
+## Performance Optimization
+
+- Use parallel jobs and matrix strategies when appropriate
+- Implement proper caching strategies for dependencies and build outputs
+- Use shallow clone for Git operations when full history isn't needed
+- Optimize Docker image builds with multi-stage builds and layer caching
+- Monitor pipeline performance and optimize bottlenecks
+- Use pipeline resource triggers efficiently
+
+## Monitoring and Observability
+
+- Include comprehensive logging throughout the pipeline
+- Use Azure Monitor and Application Insights for deployment tracking
+- Implement proper notification strategies for failures and successes
+- Include deployment health checks and automated rollback triggers
+- Use pipeline analytics to identify improvement opportunities
+- Document pipeline behavior and troubleshooting steps
+
+## Template and Reusability
+
+- Create pipeline templates for common patterns
+- Use extends templates for complete pipeline inheritance
+- Implement step templates for reusable task sequences
+- Use variable templates for complex variable logic
+- Version templates appropriately for stability
+- Document template parameters and usage examples
+
+## Branch and Trigger Strategy
+
+- Implement appropriate triggers for different branch types
+- Use path filters to trigger builds only when relevant files change
+- Configure proper CI/CD triggers for main/master branches
+- Use pull request triggers for code validation
+- Implement scheduled triggers for maintenance tasks
+- Consider resource triggers for multi-repository scenarios
+
+## Example Structure
+
+```yaml
+# azure-pipelines.yml
+trigger:
+  branches:
+    include:
+      - main
+      - develop
+  paths:
+    exclude:
+      - docs/*
+      - README.md
+
+variables:
+  - group: shared-variables
+  - name: buildConfiguration
+    value: 'Release'
+
+stages:
+  - stage: Build
+    displayName: 'Build and Test'
+    jobs:
+      - job: Build
+        displayName: 'Build Application'
+        pool:
+          vmImage: 'ubuntu-latest'
+        steps:
+          - task: UseDotNet@2
+            displayName: 'Use .NET SDK'
+            inputs:
+              version: '8.x'
+          
+          - task: DotNetCoreCLI@2
+            displayName: 'Restore dependencies'
+            inputs:
+              command: 'restore'
+              projects: '**/*.csproj'
+          
+          - task: DotNetCoreCLI@2
+            displayName: 'Build application'
+            inputs:
+              command: 'build'
+              projects: '**/*.csproj'
+              arguments: '--configuration $(buildConfiguration) --no-restore'
+
+  - stage: Deploy
+    displayName: 'Deploy to Staging'
+    dependsOn: Build
+    condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))
+    jobs:
+      - deployment: DeployToStaging
+        displayName: 'Deploy to Staging Environment'
+        environment: 'staging'
+        strategy:
+          runOnce:
+            deploy:
+              steps:
+                - download: current
+                  displayName: 'Download drop artifact'
+                  artifact: drop
+                - task: AzureWebApp@1
+                  displayName: 'Deploy to Azure Web App'
+                  inputs:
+                    azureSubscription: 'staging-service-connection'
+                    appType: 'webApp'
+                    appName: 'myapp-staging'
+                    package: '$(Pipeline.Workspace)/drop/**/*.zip'
+```
+
+## Common Anti-Patterns to Avoid
+
+- Hardcoding sensitive values directly in YAML files
+- Using overly broad triggers that cause unnecessary builds
+- Mixing build and deployment logic in a single stage
+- Not implementing proper error handling and cleanup
+- Using deprecated task versions without upgrade plans
+- Creating monolithic pipelines that are difficult to maintain
+- Not using proper naming conventions for clarity
+- Ignoring pipeline security best practices