@abarcenas/ai-workflow-template 1.1.0

package/.github/instructions/shell.instructions.md

@@ -0,0 +1,132 @@
+---
+description: "Shell scripting best practices and conventions for bash, sh, zsh, and other shells"
+applyTo: "**/*.sh"
+---
+
+# Shell Scripting Guidelines
+
+Instructions for writing clean, safe, and maintainable shell scripts for bash, sh, zsh, and other shells.
+
+## General Principles
+
+- Generate code that is clean, simple, and concise
+- Ensure scripts are easily readable and understandable
+- Add comments where helpful for understanding how the script works
+- Generate concise and simple echo outputs to provide execution status
+- Avoid unnecessary echo output and excessive logging
+- Use shellcheck for static analysis when available
+- Assume scripts are for automation and testing rather than production systems unless specified otherwise
+- Prefer safe expansions: double-quote variable references (`"$var"`), use `${var}` for clarity, and avoid `eval`
+- Use modern Bash features (`[[ ]]`, `local`, arrays) when portability requirements allow; fall back to POSIX constructs only when needed
+- Choose reliable parsers for structured data instead of ad-hoc text processing
+
+## Error Handling & Safety
+
+- Always enable `set -euo pipefail` to fail fast on errors, catch unset variables, and surface pipeline failures
+- Validate all required parameters before execution
+- Provide clear error messages with context
+- Use `trap` to clean up temporary resources or handle unexpected exits when the script terminates
+- Declare immutable values with `readonly` (or `declare -r`) to prevent accidental reassignment
+- Use `mktemp` to create temporary files or directories safely and ensure they are removed in your cleanup handler
+
+## Script Structure
+
+- Start with a clear shebang: `#!/bin/bash` unless specified otherwise
+- Include a header comment explaining the script's purpose
+- Define default values for all variables at the top
+- Use functions for reusable code blocks
+- Create reusable functions instead of repeating similar blocks of code
+- Keep the main execution flow clean and readable
+
+## Working with JSON and YAML
+
+- Prefer dedicated parsers (`jq` for JSON, `yq` for YAML—or `jq` on JSON converted via `yq`) over ad-hoc text processing with `grep`, `awk`, or shell string splitting
+- When `jq`/`yq` are unavailable or not appropriate, choose the next most reliable parser available in your environment, and be explicit about how it should be used safely
+- Validate that required fields exist and handle missing/invalid data paths explicitly (e.g., by checking `jq` exit status or using `// empty`)
+- Quote jq/yq filters to prevent shell expansion and prefer `--raw-output` when you need plain strings
+- Treat parser errors as fatal: combine with `set -euo pipefail` or test command success before using results
+- Document parser dependencies at the top of the script and fail fast with a helpful message if `jq`/`yq` (or alternative tools) are required but not installed
+
+```bash
+#!/bin/bash
+
+# ============================================================================
+# Script Description Here
+# ============================================================================
+
+set -euo pipefail
+
+cleanup() {
+    # Remove temporary resources or perform other teardown steps as needed
+    if [[ -n "${TEMP_DIR:-}" && -d "$TEMP_DIR" ]]; then
+        rm -rf "$TEMP_DIR"
+    fi
+}
+
+trap cleanup EXIT
+
+# Default values
+RESOURCE_GROUP=""
+REQUIRED_PARAM=""
+OPTIONAL_PARAM="default-value"
+readonly SCRIPT_NAME="$(basename "$0")"
+
+TEMP_DIR=""
+
+# Functions
+usage() {
+    echo "Usage: $SCRIPT_NAME [OPTIONS]"
+    echo "Options:"
+    echo "  -g, --resource-group   Resource group (required)"
+    echo "  -h, --help            Show this help"
+    exit 0
+}
+
+validate_requirements() {
+    if [[ -z "$RESOURCE_GROUP" ]]; then
+        echo "Error: Resource group is required"
+        exit 1
+    fi
+}
+
+main() {
+    validate_requirements
+
+    TEMP_DIR="$(mktemp -d)"
+    if [[ ! -d "$TEMP_DIR" ]]; then
+        echo "Error: failed to create temporary directory" >&2
+        exit 1
+    fi
+
+    echo "============================================================================"
+    echo "Script Execution Started"
+    echo "============================================================================"
+
+    # Main logic here
+
+    echo "============================================================================"
+    echo "Script Execution Completed"
+    echo "============================================================================"
+}
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        -g|--resource-group)
+            RESOURCE_GROUP="$2"
+            shift 2
+            ;;
+        -h|--help)
+            usage
+            ;;
+        *)
+            echo "Unknown option: $1"
+            exit 1
+            ;;
+    esac
+done
+
+# Execute main function
+main "$@"
+
+```

package/.github/instructions/task-implementation.instructions.md

@@ -0,0 +1,203 @@
+---
+applyTo: "**/.copilot-tracking/changes/*.md"
+description: "Instructions for implementing task plans with progressive tracking and change record - Brought to you by microsoft/edge-ai"
+---
+
+# Task Plan Implementation Instructions
+
+You will implement your specific task plan located in `.copilot-tracking/plans/**` and `.copilot-tracking/details/**`. Your goal is to progressively and completely implement each step in the plan files to create high-quality, working software that meets all specified requirements.
+
+Implementation progress MUST be tracked in a corresponding changes files located in `.copilot-tracking/changes/**`.
+
+## Core Implementation Process
+
+### 1. Plan Analysis and Preparation
+
+**MUST complete before starting implementation:**
+
+- **MANDATORY**: Read and fully understand the complete plan file including scope, objectives, all phases, and every checklist item
+- **MANDATORY**: Read and fully understand the corresponding changes file completely - if any parts are missing from context, read the entire file back in using `read_file`
+- **MANDATORY**: Identify all referenced files mentioned in the plan and examine them for context
+- **MANDATORY**: Understand current project structure and conventions
+
+### 2. Systematic Implementation Process
+
+**Implement each task in the plan systematically:**
+
+1. **Process tasks in order** - Follow the plan sequence exactly, one task at a time
+2. **MANDATORY before implementing any task:**
+   - **ALWAYS ensure implementation is associated with a specific task from the plan**
+   - **ALWAYS read the entire details section for that task from the associated details markdown file in `.copilot-tracking/details/**`\*\*
+   - **FULLY understand all implementation details before proceeding**
+   - Gather any additional required context as needed
+
+3. **Implement the task completely with working code:**
+   - Follow existing code patterns and conventions from the workspace
+   - Create working functionality that meets all task requirements specified in the details
+   - Include proper error handling, documentation, and follow best practices
+
+4. **Mark task complete and update changes tracking:**
+   - Update plan file: change `[ ]` to `[x]` for completed task
+   - **MANDATORY after completing EVERY task**: Update the changes file by appending to the appropriate Added, Modified, or Removed sections with relative file paths and one-sentence summary of what was implemented
+   - **MANDATORY**: If any changes diverge from the task plan and details, specifically call out within the relevant section that the change was made outside of the plan and include the specific reason
+   - If ALL tasks in a phase are complete `[x]`, mark the phase header as complete `[x]`
+
+### 3. Implementation Quality Standards
+
+**Every implementation MUST:**
+
+- Follow existing workspace patterns and conventions (check `copilot/` folder for standards)
+- Implement complete, working functionality that meets all task requirements
+- Include appropriate error handling and validation
+- Use consistent naming conventions and code structure from the workspace
+- Add necessary documentation and comments for complex logic
+- Ensure compatibility with existing systems and dependencies
+
+### 4. Continuous Progress and Validation
+
+**After implementing each task:**
+
+1. Validate the changes made against the task requirements from the details file
+2. Fix any problems before moving to the next task
+3. **MANDATORY**: Update the plan file to mark completed tasks `[x]`
+4. **MANDATORY after EVERY task completion**: Update the changes file by appending to Added, Modified, or Removed sections with relative file paths and one-sentence summary of what was implemented
+5. Continue to the next unchecked task
+
+**Continue until:**
+
+- All tasks in the plan are marked complete `[x]`
+- All specified files have been created or updated with working code
+- All success criteria from the plan have been verified
+
+### 5. Reference Gathering Guidelines
+
+**When gathering external references:**
+
+- Focus on practical implementation examples over theoretical documentation
+- Validate that external sources contain actual usable patterns
+- Adapt external patterns to match workspace conventions and standards
+
+**When implementing from references:**
+
+- Follow workspace patterns and conventions first, external patterns second
+- Implement complete, working functionality rather than just examples
+- Ensure all dependencies and configurations are properly integrated
+- Ensure implementations work within the existing project structure
+
+### 6. Completion and Documentation
+
+**Implementation is complete when:**
+
+- All plan tasks are marked complete `[x]`
+- All specified files exist with working code
+- All success criteria from the plan are verified
+- No implementation errors remain
+
+**Final step - update changes file with release summary:**
+
+- Add Release Summary section only after ALL phases are marked complete `[x]`
+- Document complete file inventory and overall implementation summary for release documentation
+
+### 7. Problem Resolution
+
+**When encountering implementation issues:**
+
+- Document the specific problem clearly
+- Try alternative approaches or search terms
+- Use workspace patterns as fallback when external references fail
+- Continue with available information rather than stopping completely
+- Note any unresolved issues in the plan file for future reference
+
+## Implementation Workflow
+
+```
+1. Read and fully understand plan file and all checklists completely
+2. Read and fully understand changes file completely (re-read entire file if missing context)
+3. For each unchecked task:
+   a. Read entire details section for that task from details markdown file
+   b. Fully understand all implementation requirements
+   c. Implement task with working code following workspace patterns
+   d. Validate implementation meets task requirements
+   e. Mark task complete [x] in plan file
+   f. Update changes file with Added, Modified, or Removed entries
+   g. Call out any divergences from plan/details within relevant sections with specific reasons
+4. Repeat until all tasks complete
+5. Only after ALL phases are complete [x]: Add final Release Summary to changes file
+```
+
+## Success Criteria
+
+Implementation is complete when:
+
+- ✅ All plan tasks are marked complete `[x]`
+- ✅ All specified files contain working code
+- ✅ Code follows workspace patterns and conventions
+- ✅ All functionality works as expected within the project
+- ✅ Changes file is updated after every task completion with Added, Modified, or Removed entries
+- ✅ Changes file documents all phases with detailed release-ready documentation and final release summary
+
+## Template Changes File
+
+Use the following as a template for the changes file that tracks implementation progress for releases.
+Replace `{{ }}` with appropriate values. Create this file in `./.copilot-tracking/changes/` with filename: `YYYYMMDD-task-description-changes.md`
+
+**IMPORTANT**: Update this file after EVERY task completion by appending to Added, Modified, or Removed sections.
+**MANDATORY**: Always include the following at the top of the changes file: `<!-- markdownlint-disable-file -->`
+
+<!-- <changes-template> -->
+
+```markdown
+<!-- markdownlint-disable-file -->
+
+# Release Changes: {{task name}}
+
+**Related Plan**: {{plan-file-name}}
+**Implementation Date**: {{YYYY-MM-DD}}
+
+## Summary
+
+{{Brief description of the overall changes made for this release}}
+
+## Changes
+
+### Added
+
+- {{relative-file-path}} - {{one sentence summary of what was implemented}}
+
+### Modified
+
+- {{relative-file-path}} - {{one sentence summary of what was changed}}
+
+### Removed
+
+- {{relative-file-path}} - {{one sentence summary of what was removed}}
+
+## Release Summary
+
+**Total Files Affected**: {{number}}
+
+### Files Created ({{count}})
+
+- {{file-path}} - {{purpose}}
+
+### Files Modified ({{count}})
+
+- {{file-path}} - {{changes-made}}
+
+### Files Removed ({{count}})
+
+- {{file-path}} - {{reason}}
+
+### Dependencies & Infrastructure
+
+- **New Dependencies**: {{list-of-new-dependencies}}
+- **Updated Dependencies**: {{list-of-updated-dependencies}}
+- **Infrastructure Changes**: {{infrastructure-updates}}
+- **Configuration Updates**: {{configuration-changes}}
+
+### Deployment Notes
+
+{{Any specific deployment considerations or steps}}
+```
+
+<!-- </changes-template> -->

package/.github/instructions/typescript.instructions.md

@@ -0,0 +1,114 @@
+---
+description: "Guidelines for TypeScript Development targeting TypeScript 5.x and ES2022 output"
+applyTo: "**/*.ts"
+---
+
+# TypeScript Development
+
+> These instructions assume projects are built with TypeScript 5.x (or newer) compiling to an ES2022 JavaScript baseline. Adjust guidance if your runtime requires older language targets or down-level transpilation.
+
+## Core Intent
+
+- Respect the existing architecture and coding standards.
+- Prefer readable, explicit solutions over clever shortcuts.
+- Extend current abstractions before inventing new ones.
+- Prioritize maintainability and clarity, short methods and classes, clean code.
+
+## General Guardrails
+
+- Target TypeScript 5.x / ES2022 and prefer native features over polyfills.
+- Use pure ES modules; never emit `require`, `module.exports`, or CommonJS helpers.
+- Rely on the project's build, lint, and test scripts unless asked otherwise.
+- Note design trade-offs when intent is not obvious.
+
+## Project Organization
+
+- Follow the repository's folder and responsibility layout for new code.
+- Use kebab-case filenames (e.g., `user-session.ts`, `data-service.ts`) unless told otherwise.
+- Keep tests, types, and helpers near their implementation when it aids discovery.
+- Reuse or extend shared utilities before adding new ones.
+
+## Naming & Style
+
+- Use PascalCase for classes, interfaces, enums, and type aliases; camelCase for everything else.
+- Skip interface prefixes like `I`; rely on descriptive names.
+- Name things for their behavior or domain meaning, not implementation.
+
+## Formatting & Style
+
+- Run the repository's lint/format scripts (e.g., `npm run lint`) before submitting.
+- Match the project's indentation, quote style, and trailing comma rules.
+- Keep functions focused; extract helpers when logic branches grow.
+- Favor immutable data and pure functions when practical.
+
+## Type System Expectations
+
+- Avoid `any` (implicit or explicit); prefer `unknown` plus narrowing.
+- Use discriminated unions for realtime events and state machines.
+- Centralize shared contracts instead of duplicating shapes.
+- Express intent with TypeScript utility types (e.g., `Readonly`, `Partial`, `Record`).
+
+## Async, Events & Error Handling
+
+- Use `async/await`; wrap awaits in try/catch with structured errors.
+- Guard edge cases early to avoid deep nesting.
+- Send errors through the project's logging/telemetry utilities.
+- Surface user-facing errors via the repository's notification pattern.
+- Debounce configuration-driven updates and dispose resources deterministically.
+
+## Architecture & Patterns
+
+- Follow the repository's dependency injection or composition pattern; keep modules single-purpose.
+- Observe existing initialization and disposal sequences when wiring into lifecycles.
+- Keep transport, domain, and presentation layers decoupled with clear interfaces.
+- Supply lifecycle hooks (e.g., `initialize`, `dispose`) and targeted tests when adding services.
+
+## External Integrations
+
+- Instantiate clients outside hot paths and inject them for testability.
+- Never hardcode secrets; load them from secure sources.
+- Apply retries, backoff, and cancellation to network or IO calls.
+- Normalize external responses and map errors to domain shapes.
+
+## Security Practices
+
+- Validate and sanitize external input with schema validators or type guards.
+- Avoid dynamic code execution and untrusted template rendering.
+- Encode untrusted content before rendering HTML; use framework escaping or trusted types.
+- Use parameterized queries or prepared statements to block injection.
+- Keep secrets in secure storage, rotate them regularly, and request least-privilege scopes.
+- Favor immutable flows and defensive copies for sensitive data.
+- Use vetted crypto libraries only.
+- Patch dependencies promptly and monitor advisories.
+
+## Configuration & Secrets
+
+- Reach configuration through shared helpers and validate with schemas or dedicated validators.
+- Handle secrets via the project's secure storage; guard `undefined` and error states.
+- Document new configuration keys and update related tests.
+
+## UI & UX Components
+
+- Sanitize user or external content before rendering.
+- Keep UI layers thin; push heavy logic to services or state managers.
+- Use messaging or events to decouple UI from business logic.
+
+## Testing Expectations
+
+- Add or update unit tests with the project's framework and naming style.
+- Expand integration or end-to-end suites when behavior crosses modules or platform APIs.
+- Run targeted test scripts for quick feedback before submitting.
+- Avoid brittle timing assertions; prefer fake timers or injected clocks.
+
+## Performance & Reliability
+
+- Lazy-load heavy dependencies and dispose them when done.
+- Defer expensive work until users need it.
+- Batch or debounce high-frequency events to reduce thrash.
+- Track resource lifetimes to prevent leaks.
+
+## Documentation & Comments
+
+- Add JSDoc to public APIs; include `@remarks` or `@example` when helpful.
+- Write comments that capture intent, and remove stale notes during refactors.
+- Update architecture or design docs when introducing significant patterns.