@northbridge-security/secureai 0.1.13

package/tasks/README.md

@@ -0,0 +1,880 @@
+# GoTask Task Libraries
+
+This directory contains GoTask task libraries for the AI Toolkit project. Tasks are organized by functionality into separate YAML files.
+
+## Index
+
+Jump to a specific task library:
+
+- [Main Taskfile](#main-taskfile) - Core tasks and library includes
+- [AWS](#aws-cli-operations-awsyml) - AWS SSO authentication
+- [Bash](#bash-linting--formatting-bashyml) - Shell script linting and formatting
+- [Bun](#bun-development-tasks-bunyml) - Build, test, lint, format
+- [Claude](#claude-code--mcp-claudeyml) - MCP server management
+- [Docker](#docker-operations-dockeryml) - Container and image management
+- [Docs](#api-documentation-docsyml) - API documentation generation
+- [Git](#git--github-operations-gityml) - Git and GitHub operations
+- [GoTask](#gotask-utilities-gotaskyml) - Task development utilities
+- [JSON](#json-linting--validation-jsonyml) - JSON linting and formatting
+- [Markdown](#markdown-linting--validation-markdownyml) - Markdown linting
+- [1Password](#1password-secret-management-onepasswordyml) - Secret management
+- [Security](#security-scanning-securityyml) - SAST and secret scanning
+- [SonarQube](#sonarqube-code-quality-sonaryml) - Code quality analysis
+- [YAML](#yaml-linting--validation-yamlyml) - YAML linting and formatting
+
+---
+
+## Main Taskfile
+
+**File:** [../Taskfile.yml](../Taskfile.yml)
+
+Primary task runner configuration that includes all other task libraries.
+
+**Core Tasks** (flattened from [bun.yml](bun.yml)):
+
+| Task                        | Alias  | Description                                       |
+| --------------------------- | ------ | ------------------------------------------------- |
+| `task setup`                | -      | Setup development environment (run after cloning) |
+| `task install`              | `i`    | Install dependencies                              |
+| `task build`                | `b`    | Build the project                                 |
+| `task rebuild`              | `rb`   | Clean and rebuild project                         |
+| `task clean`                | `c`    | Clean build artifacts and temporary files         |
+| `task dev`                  | `d`    | Run in development mode                           |
+| `task test`                 | `t`    | Run unit tests                                    |
+| `task test:integration`     | `ti`   | Run integration tests                             |
+| `task test:coverage`        | `cov`  | Run tests with coverage                           |
+| `task test:coverage:report` | `covr` | Display coverage report                           |
+| `task lint`                 | `l`    | Run linter                                        |
+| `task lint:fix`             | `lf`   | Run linter with auto-fix                          |
+| `task format`               | `f`    | Format code                                       |
+| `task typecheck`            | `tc`   | Type check TypeScript                             |
+| `task ci`                   | -      | Run CI checks (lint, typecheck, test, build)      |
+
+**Included Task Libraries:**
+
+| Namespace  | Alias | File                               | Description                   |
+| ---------- | ----- | ---------------------------------- | ----------------------------- |
+| `aws`      | -     | [aws.yml](aws.yml)                 | AWS CLI operations            |
+| `bash`     | -     | [bash.yml](bash.yml)               | Bash linting & formatting     |
+| `claude`   | `cd`  | [claude.yml](claude.yml)           | Claude Code & MCP management  |
+| `docker`   | `dk`  | [docker.yml](docker.yml)           | Docker container management   |
+| `docs`     | -     | [docs.yml](docs.yml)               | API documentation generation  |
+| `git`      | -     | [git.yml](git.yml)                 | Git & GitHub operations       |
+| `gotask`   | `gt`  | [gotask.yml](gotask.yml)           | Task development utilities    |
+| `json`     | -     | [json.yml](json.yml)               | JSON linting & validation     |
+| `markdown` | `md`  | [markdown.yml](markdown.yml)       | Markdown linting & validation |
+| `op`       | `1p`  | [onepassword.yml](onepassword.yml) | 1Password secret management   |
+| `security` | `s`   | [security.yml](security.yml)       | Security scanning             |
+| `sonar`    | -     | [sonar.yml](sonar.yml)             | SonarQube code quality        |
+| `yaml`     | `yml` | [yaml.yml](yaml.yml)               | YAML linting & validation     |
+
+---
+
+## AWS CLI Operations ([aws.yml](aws.yml))
+
+Utilities for AWS SSO authentication and credential management.
+
+**Commands:**
+
+| Task             | Alias | Description                           |
+| ---------------- | ----- | ------------------------------------- |
+| `task aws:login` | `l`   | Check and refresh AWS SSO credentials |
+
+**Usage:**
+
+```bash
+# Login with profile from environment or .env
+task aws:login
+
+# Login with specific profile
+task aws:login PROFILE=my-profile
+
+# Using AWS_PROFILE environment variable
+export AWS_PROFILE=my-profile
+task aws:login
+```
+
+**Features:**
+
+- Checks if credentials are valid before prompting
+- Loads profile from parameter, environment, or `.env` file
+- Integrates with 1Password for secret management
+- Only prompts for SSO login if credentials expired
+
+**Requirements:**
+
+- AWS CLI v2 must be installed
+- AWS SSO must be configured in `~/.aws/config`
+- `AWS_PROFILE` must be set via parameter, environment, or `.env` file
+
+---
+
+## Bash Linting & Formatting ([bash.yml](bash.yml))
+
+Bash script validation, linting, and auto-formatting with global tool installation.
+
+**Implementation:** Task logic is in TypeScript ([src/tasks/bash/](../src/tasks/bash/)) for maintainability and testability.
+
+**Commands:**
+
+| Task                     | Alias | Description                      |
+| ------------------------ | ----- | -------------------------------- |
+| `task bash:lint`         | `l`   | Lint bash files with shellcheck  |
+| `task bash:format`       | `f`   | Format bash files with shfmt     |
+| `task bash:format:check` | `fc`  | Check formatting without changes |
+| `task bash:setup`        | `s`   | Install bash tools globally      |
+
+**Usage:**
+
+```bash
+# Lint all bash files (quiet on success)
+task bash:lint
+
+# Lint specific pattern
+task bash:lint FILES="*.sh"
+task bash:lint FILES="scripts/**/*.sh"
+
+# Show output even on success
+VERBOSE=1 task bash:lint
+
+# Format all bash files
+task bash:format
+
+# Check formatting without making changes
+task bash:format:check
+
+# Install tools globally (one-time setup)
+task bash:setup
+```
+
+**Features:**
+
+- Quiet output on success (use `VERBOSE=1` for details)
+- File pattern support with glob expansion
+- Auto-formatting with shfmt
+- Global tool installation via `task bash:setup`
+- Cross-platform support (macOS, Linux)
+
+**Tools Installed by `setup`:**
+
+- **shellcheck** - Bash linting and validation
+- **shfmt** - Bash script formatting
+
+**Default Patterns:**
+
+`*.sh,**/*.sh,bin/*,scripts/**/*.sh`
+
+---
+
+## Bun Development Tasks ([bun.yml](bun.yml))
+
+Core development tasks for building, testing, and maintaining the project.
+
+**Commands:**
+
+| Task                        | Alias  | Description                                  |
+| --------------------------- | ------ | -------------------------------------------- |
+| `task install`              | `i`    | Install dependencies                         |
+| `task build`                | `b`    | Build the project                            |
+| `task rebuild`              | `rb`   | Clean and rebuild project                    |
+| `task clean`                | `c`    | Clean build artifacts and temporary files    |
+| `task dev`                  | `d`    | Run in development mode                      |
+| `task lint`                 | `l`    | Run linter                                   |
+| `task lint:fix`             | `lf`   | Run linter with auto-fix                     |
+| `task format`               | `f`    | Format code                                  |
+| `task typecheck`            | `tc`   | Type check TypeScript                        |
+| `task test`                 | `t`    | Run unit tests                               |
+| `task test:integration`     | `ti`   | Run integration tests                        |
+| `task test:coverage`        | `cov`  | Run tests with coverage                      |
+| `task test:coverage:report` | `covr` | Display coverage report                      |
+| `task ci`                   | -      | Run CI checks (lint, typecheck, test, build) |
+
+**Usage:**
+
+```bash
+# Development workflow
+task install
+task build
+task test
+
+# Lint and auto-fix
+task lint:fix
+
+# Run tests with coverage
+task test:coverage
+
+# Show coverage report with files below threshold
+task test:coverage:report THRESHOLD=80
+
+# Clean everything including git worktrees
+task clean
+
+# Full rebuild
+task rebuild
+
+# Run CI checks locally
+task ci
+```
+
+**Features:**
+
+- Auto-detection of ESLint, Biome, and Prettier
+- Coverage tracking with low-coverage file highlighting
+- Git worktree cleanup in clean task
+- Integration with 1Password for secrets
+- Parallel test execution support
+
+---
+
+## Claude Code & MCP ([claude.yml](claude.yml))
+
+Tasks for managing Claude Code integration and MCP server installations.
+
+**MCP Server Management:**
+
+| Task                      | Alias | Description                    |
+| ------------------------- | ----- | ------------------------------ |
+| `task claude:mcp:install` | `mi`  | Install MCP server globally    |
+| `task claude:mcp:verify`  | `mv`  | Verify MCP server installation |
+| `task claude:mcp:status`  | `ms`  | Show MCP server status         |
+| `task claude:mcp:remove`  | `mr`  | Remove MCP server              |
+
+**Installer Testing:**
+
+| Task                               | Alias | Description                       |
+| ---------------------------------- | ----- | --------------------------------- |
+| `task claude:installer:test`       | `it`  | Run complete installer test suite |
+| `task claude:installer:test:force` | `itf` | Test force reinstall              |
+| `task claude:installer:test:clean` | `itc` | Clean up test installations       |
+
+---
+
+## Docker Operations ([docker.yml](docker.yml))
+
+Docker container management, image operations, and security scanning.
+
+**Image Operations:**
+
+| Task                | Alias | Description            | Parameters                 |
+| ------------------- | ----- | ---------------------- | -------------------------- |
+| `task docker:build` | -     | Build Docker image     | `IMAGE=... TAG=... PATH=.` |
+| `task docker:tag`   | -     | Tag Docker image       | `SOURCE=... TARGET=...`    |
+| `task docker:push`  | -     | Push image to registry | `IMAGE=... TAG=...`        |
+
+**GitHub Container Registry:**
+
+| Task                    | Alias | Description      | Parameters                             |
+| ----------------------- | ----- | ---------------- | -------------------------------------- |
+| `task docker:git:login` | -     | Login to ghcr.io | `USER=... TOKEN=...`                   |
+| `task docker:git:push`  | -     | Push to ghcr.io  | `IMAGE=... TAG=... USER=... TOKEN=...` |
+
+**Security Scanning:**
+
+| Task                          | Alias | Description                           | Parameters          |
+| ----------------------------- | ----- | ------------------------------------- | ------------------- |
+| `task docker:scan`            | -     | Scan image for vulnerabilities        | `IMAGE=... TAG=...` |
+| `task docker:scan:dockerfile` | `df`  | Scan Dockerfile for misconfigurations | `FILE=...`          |
+| `task docker:scan:init`       | -     | Initialize Trivy cache                | -                   |
+
+**Linux Debug Environment:**
+
+| Task                       | Alias | Description                 |
+| -------------------------- | ----- | --------------------------- |
+| `task docker:linux:build`  | `b`   | Build image with local code |
+| `task docker:linux:test`   | `t`   | Run E2E tests               |
+| `task docker:linux:up`     | `u`   | Start container with SSH    |
+| `task docker:linux:down`   | `d`   | Stop and remove container   |
+| `task docker:linux:status` | `st`  | Check container status      |
+| `task docker:linux:logs`   | `l`   | View container logs         |
+
+**Usage:**
+
+```bash
+# Build and scan image
+task docker:build IMAGE=myapp TAG=v1.0.0 PATH=.
+task docker:scan IMAGE=myapp TAG=v1.0.0
+
+# Scan Dockerfile before building
+task docker:scan:dockerfile FILE=Dockerfile
+task docker:scan:dockerfile FILE=docker/app/Dockerfile
+
+# Push to GitHub Container Registry
+task docker:git:push IMAGE=myapp TAG=v1.0.0 USER=username TOKEN=ghp_xxx
+
+# Also push latest tag
+task docker:git:push IMAGE=myapp TAG=v1.0.0 USER=username TOKEN=ghp_xxx LATEST=true
+
+# Linux debug environment
+task docker:linux:build && task docker:linux:test
+task docker:linux:up
+ssh -p 2222 developer@localhost
+task docker:linux:down
+```
+
+**Features:**
+
+- Trivy-based vulnerability scanning for images
+- Dockerfile misconfiguration scanning (security best practices)
+- GitHub Container Registry integration
+- Quiet mode by default (use `VERBOSE=true` for details)
+- Cached Trivy database via Docker volume
+- Linux debug environment for cross-platform testing
+
+**Requirements:**
+
+- Docker must be installed and running
+- For GHCR: GitHub token with `write:packages` permission
+
+---
+
+## API Documentation ([docs.yml](docs.yml))
+
+TypeDoc-based API documentation generation in Markdown format.
+
+**Commands:**
+
+| Task                 | Alias | Description                       |
+| -------------------- | ----- | --------------------------------- |
+| `task docs:generate` | `g`   | Generate API docs from TypeScript |
+| `task docs:clean`    | `c`   | Remove generated documentation    |
+| `task docs:watch`    | `w`   | Watch for changes and regenerate  |
+| `task docs:view`     | `v`   | Open generated docs               |
+| `task docs:rebuild`  | `r`   | Clean and regenerate docs         |
+
+**Usage:**
+
+```bash
+# Generate API documentation
+task docs:generate
+
+# Watch and auto-regenerate on changes
+task docs:watch
+
+# View generated docs
+task docs:view
+
+# Clean and regenerate
+task docs:rebuild
+```
+
+**Features:**
+
+- TypeDoc integration for TypeScript documentation
+- Markdown output format
+- Auto-open in VSCode or system viewer
+- Watch mode for development
+
+**Output:**
+
+Documentation generated in `docs/api/` directory.
+
+---
+
+## Git & GitHub Operations ([git.yml](git.yml))
+
+Tasks for Git operations, GitHub PR management, and repository utilities.
+
+**Repository Utilities:**
+
+| Task                      | Alias    | Description                          |
+| ------------------------- | -------- | ------------------------------------ |
+| `task git:repo:root`      | `root`   | Get repository root path             |
+| `task git:repo:url`       | `url`    | Get repository HTTPS URL             |
+| `task git:branch:current` | `branch` | Get current branch name              |
+| `task git:branch:default` | `main`   | Get default branch (main/master)     |
+| `task git:branch:prune`   | `prune`  | Delete local branches gone on remote |
+| `task git:token`          | `token`  | Get GitHub authentication token      |
+
+**Pull Request Management:**
+
+| Task                   | Alias | Description                      |
+| ---------------------- | ----- | -------------------------------- |
+| `task git:pr:create`   | `pr`  | Create/update draft PR from file |
+| `task git:pr:open`     | `pro` | Open current PR in browser       |
+| `task git:pr:list`     | `prl` | List pull requests               |
+| `task git:pr:comments` | `com` | Get all comments from current PR |
+
+**GitHub Actions:**
+
+| Task                   | Alias  | Description                |
+| ---------------------- | ------ | -------------------------- |
+| `task git:runs:log`    | `logs` | Download workflow run logs |
+| `task git:actions:pin` | `pin`  | Pin actions to commit SHAs |
+
+**Security:**
+
+| Task             | Alias   | Description                    |
+| ---------------- | ------- | ------------------------------ |
+| `task git:leaks` | `leaks` | Scan for secrets with gitleaks |
+| `task git:cve`   | `cve`   | Download CVEs for repository   |
+
+**Usage:**
+
+```bash
+# Repository utilities
+REPO_ROOT=$(task git:repo:root)
+REPO_URL=$(task git:repo:url)
+CURRENT_BRANCH=$(task git:branch:current)
+DEFAULT_BRANCH=$(task git:branch:default)
+
+# Create PR from default file (.pr.local.md)
+task git:pr:create
+
+# Create PR from custom file
+task git:pr:create FILE=.pr.custom.md
+
+# List open PRs
+task git:pr:list LIMIT=20 STATE=open
+
+# Get all PR comments
+task git:pr:comments
+
+# Download workflow run logs
+task git:runs:log                              # Latest failed run
+task git:runs:log STATE=all ALL=true           # All runs (any state)
+task git:runs:log RUN_ID=12345678              # Specific run
+task git:runs:log WORKFLOW="Tests" STATE=all   # All test runs
+
+# Pin GitHub Actions to commit SHAs
+task git:actions:pin                           # Check for unpinned actions
+task git:actions:pin UPGRADE=1                 # Upgrade and pin actions
+task git:actions:pin CHECK=1                   # Check only (no changes)
+
+# Security scanning
+task git:leaks                                 # Scan for secrets
+task git:cve MIN_SEVERITY=medium               # Download CVEs
+```
+
+**Features:**
+
+- Automatically pushes branch if not on remote
+- Loads GitHub token from 1Password if configured
+- Parses title from `# Heading` in markdown file
+- Opens PR in browser after creation
+- Cross-platform browser opening (macOS, Linux, Windows)
+- Workflow log aggregation and filtering
+- GitHub Actions pinning for security
+
+**Requirements:**
+
+- GitHub CLI (`gh`) must be installed: `brew install gh`
+- `GITHUB_TOKEN` or `GH_TOKEN` environment variable must be set
+- PR file must exist with format:
+
+  ```markdown
+  # PR Title
+
+  PR body content here...
+  ```
+
+---
+
+## GoTask Utilities ([gotask.yml](gotask.yml))
+
+Development tools and utilities for creating and managing task files.
+
+**Task Development:**
+
+| Task                     | Alias | Description                         |
+| ------------------------ | ----- | ----------------------------------- |
+| `task gotask:format`     | `f`   | Format default task in Taskfile     |
+| `task gotask:new:task`   | `nt`  | Create new task in Taskfile.yml     |
+| `task gotask:new:script` | `ns`  | Create new TypeScript task script   |
+| `task gotask:validate`   | `v`   | Validate all Taskfile.yml syntax    |
+| `task gotask:deps:check` | `dc`  | Check for missing task dependencies |
+
+**Setup & Configuration:**
+
+| Task                           | Alias | Description                                  |
+| ------------------------------ | ----- | -------------------------------------------- |
+| `task gotask:setup:extensions` | `se`  | Install recommended VSCode/Cursor extensions |
+
+**Documentation:**
+
+| Task                        | Alias | Description                 |
+| --------------------------- | ----- | --------------------------- |
+| `task gotask:docs:generate` | `dg`  | Generate task documentation |
+| `task gotask:docs:view`     | `dv`  | View best practices guide   |
+| `task gotask:docs:edit`     | `de`  | Edit best practices guide   |
+
+**Templates:**
+
+| Task                         | Alias | Description                  |
+| ---------------------------- | ----- | ---------------------------- |
+| `task gotask:template:basic` | `tb`  | Generate basic task template |
+| `task gotask:template:build` | `tbu` | Generate build task template |
+| `task gotask:template:test`  | `tt`  | Generate test task template  |
+
+---
+
+## JSON Linting & Validation ([json.yml](json.yml))
+
+JSON file validation, linting, and auto-formatting with built-in JSON parser.
+
+**Implementation:** Task logic is in TypeScript ([src/tasks/json/](../src/tasks/json/)) for maintainability.
+
+**Commands:**
+
+| Task                 | Alias | Description              |
+| -------------------- | ----- | ------------------------ |
+| `task json:lint`     | `l`   | Lint JSON files          |
+| `task json:lint:fix` | `lf`  | Auto-fix JSON formatting |
+
+**Usage:**
+
+```bash
+# Lint all JSON files (quiet on success)
+task json:lint
+
+# Lint specific pattern
+task json:lint FILES="*.json"
+task json:lint FILES="config/**/*.json"
+
+# Show output even on success
+VERBOSE=1 task json:lint
+
+# Auto-fix formatting (pretty-print with 2-space indent)
+task json:lint:fix
+```
+
+**Features:**
+
+- Quiet output on success (use `VERBOSE=1` for details)
+- File pattern support with glob expansion
+- Auto-fix with 2-space indentation
+- Excludes node_modules, dist, and .taskmaster directories
+- Built-in JSON parser (no external dependencies)
+
+**Default Patterns:**
+
+`*.json,**/*.json,!node_modules/**,!dist/**,!.taskmaster/**`
+
+---
+
+## Markdown Linting & Validation ([markdown.yml](markdown.yml))
+
+Markdown file validation, linting, and auto-formatting using markdownlint.
+
+**Implementation:** Task logic is in TypeScript ([src/tasks/markdown/](../src/tasks/markdown/)) for maintainability.
+
+**Commands:**
+
+| Task                     | Alias | Description                          |
+| ------------------------ | ----- | ------------------------------------ |
+| `task markdown:lint`     | `l`   | Lint markdown files                  |
+| `task markdown:lint:fix` | `lf`  | Auto-fix markdown formatting         |
+| `task markdown:setup`    | `s`   | Install markdownlint & create config |
+
+**Usage:**
+
+```bash
+# Lint all markdown files (quiet on success)
+task markdown:lint
+
+# Lint specific pattern
+task markdown:lint FILES="*.md"
+task markdown:lint FILES="docs/**/*.md"
+
+# Show output even on success
+VERBOSE=1 task markdown:lint
+
+# Auto-fix formatting issues
+task markdown:lint:fix
+
+# Install markdownlint globally (one-time setup)
+task markdown:setup
+```
+
+**Features:**
+
+- Quiet output on success (use `VERBOSE=1` for details)
+- File pattern support with glob expansion
+- Auto-fix capability
+- Default config creation (`.markdownlint.yaml`)
+- Cross-platform support
+
+**Default Patterns:**
+
+`*.md,docs/**/*.md,.github/**/*.md,tasks/**/*.md`
+
+---
+
+## 1Password Secret Management ([onepassword.yml](onepassword.yml))
+
+Secure secret management using 1Password CLI. Secrets are automatically loaded by tasks that need them.
+
+**Secret Loading:**
+
+| Command                          | Alias   | Description                             |
+| -------------------------------- | ------- | --------------------------------------- |
+| `source $(task op:export)`       | `op:x`  | Load secrets into shell (interactive)   |
+| `source $(task op:export:force)` | `op:xf` | Force reload all secrets from 1Password |
+| `task op:cleanup`                | `op:c`  | Clean up temp secret files              |
+| `task op:validate`               | `op:v`  | Validate exported secrets               |
+| `task op:test`                   | `op:t`  | Test GitHub token permissions           |
+
+**How It Works:**
+
+Tasks that require secrets (like `semgrep`) automatically source secrets via secure temp files:
+
+```bash
+# Just run the task - secrets loaded automatically
+task semgrep
+
+# For interactive shell use:
+source $(task op:export)
+```
+
+**Security Features:**
+
+- Secrets stored in secure temp file (`chmod 600`)
+- 1-hour cache (idempotent, avoids repeated prompts)
+- No secrets printed to terminal
+- Unique path per repository
+- Automatic cleanup on reboot (stored in `/tmp`)
+
+---
+
+## Security Scanning ([security.yml](security.yml))
+
+Local SAST (Static Application Security Testing) scanning with semgrep and secret detection.
+
+**Commands:**
+
+| Task                       | Alias | Description                      |
+| -------------------------- | ----- | -------------------------------- |
+| `task security:scan`       | `s`   | Run semgrep security scanner     |
+| `task security:fix`        | `f`   | Auto-fix security issues         |
+| `task security:trufflehog` | `th`  | Scan for secrets with truffleHog |
+
+**Usage:**
+
+```bash
+# Run security scanner
+task security:scan
+
+# Auto-fix security issues
+task security:fix
+
+# Scan for secrets
+task security:trufflehog
+```
+
+**Features:**
+
+- Semgrep integration for SAST scanning
+- Auto-fix capability for common security issues
+- Secret scanning with truffleHog
+- Automatic tool installation if not present
+- Integration with 1Password for API tokens
+
+**Requirements:**
+
+- Semgrep installed: `pip install semgrep` or `brew install semgrep`
+- truffleHog installed: `brew install trufflehog` (auto-installed if missing)
+
+---
+
+## SonarQube Code Quality ([sonar.yml](sonar.yml))
+
+SonarQube/SonarCloud integration for code quality analysis and issue management.
+
+**Commands:**
+
+| Task                  | Alias | Description                    |
+| --------------------- | ----- | ------------------------------ |
+| `task sonar:scan`     | `s`   | Run SonarQube analysis locally |
+| `task sonar:download` | `dl`  | Download issues from SonarQube |
+| `task sonar:issues`   | `i`   | Display downloaded findings    |
+| `task sonar:setup`    | -     | Install sonar-scanner CLI      |
+
+**Usage:**
+
+```bash
+# Download analysis results
+task sonar:download
+
+# View downloaded findings
+task sonar:issues
+
+# Run local scan
+task sonar:scan
+
+# Install sonar-scanner
+task sonar:setup
+```
+
+**Features:**
+
+- Downloads complete analysis results from SonarQube/SonarCloud
+- Generates human-readable reports in `.logs/sonar/`
+- PR-specific analysis support
+- Quality gate status tracking
+- Security hotspot reporting
+- Coverage metrics integration
+- Auto-opens reports in VSCode
+
+**Configuration:**
+
+- Set `SONAR_TOKEN` in `.env` file
+- Supports 1Password references: `op://vault/item/field`
+- Project key read from `sonar-project.properties`
+
+**Requirements:**
+
+- SonarQube/SonarCloud project configured
+- `SONAR_TOKEN` environment variable set
+- `sonar-project.properties` file in repository root
+- GitHub CLI (`gh`) for PR detection
+
+---
+
+## YAML Linting & Validation ([yaml.yml](yaml.yml))
+
+YAML file validation, linting, and auto-formatting with global tool installation.
+
+**Implementation:** Task logic is in TypeScript ([src/tasks/yaml/](../src/tasks/yaml/)) following best practices for maintainability and testability.
+
+**Commands:**
+
+| Task                 | Alias | Description                 |
+| -------------------- | ----- | --------------------------- |
+| `task yaml:lint`     | `l`   | Lint YAML files             |
+| `task yaml:lint:fix` | `lf`  | Auto-fix YAML formatting    |
+| `task yaml:validate` | `v`   | Validate YAML syntax only   |
+| `task yaml:setup`    | `s`   | Install YAML tools globally |
+
+**Usage:**
+
+```bash
+# Lint all YAML files (auto-detects prettier or yamllint)
+task yaml:lint
+
+# Lint specific pattern
+task yaml:lint FILES="*.yml"
+task yaml:lint FILES="config/*.yml,tasks/*.yml"
+
+# Force specific linter
+task yaml:lint LINTER=prettier
+task yaml:lint LINTER=yamllint
+
+# Auto-fix formatting issues
+task yaml:lint:fix
+
+# Validate syntax only
+task yaml:validate
+
+# Install tools globally (one-time setup)
+task yaml:setup
+```
+
+**Features:**
+
+- Auto-detection of available linters (prettier, yamllint)
+- Global tool installation via `task yaml:setup`
+- File pattern support with glob expansion
+- Auto-fix with prettier or yq fallback
+- Default config creation (`.yamllint.yml`, `.prettierrc.yml`)
+- Cross-platform support (macOS, Linux)
+- Idempotent setup (checks existing installations)
+
+**Tools Installed by `setup`:**
+
+- **js-yaml** - YAML syntax validation
+- **prettier** - Auto-formatting (recommended)
+- **yamllint** - Style linting with rules
+
+**How It Works:**
+
+Tools are installed globally once and shared across all projects:
+
+```bash
+# First project
+cd ~/projects/ai-toolkit
+task yaml:setup          # Installs tools globally
+
+# Other projects - tools already available
+cd ~/projects/other-project
+task yaml:lint           # Works immediately
+```
+
+---
+
+## Environment Setup
+
+Tasks assume the following tools are available:
+
+- **bun** >= 1.0.0 (primary runtime)
+- **Node.js** >= 18.0.0 (fallback)
+- **Git** >= 2.0.0
+- **1Password CLI** (optional, for secret management)
+- **Claude CLI** (optional, for MCP tasks)
+- **GoTask** >= 3.0.0
+
+Install GoTask:
+
+```bash
+# macOS
+brew install go-task
+
+# Linux
+sh -c "$(curl -fsSL https://taskfile.dev/install.sh)" -- -d
+
+# Windows
+choco install go-task
+```
+
+---
+
+## Troubleshooting
+
+### Task not found
+
+```bash
+# Verify task exists
+task --list | grep task-name
+
+# Check task file is included in main Taskfile.yml
+cat Taskfile.yml | grep "includes:"
+```
+
+### Script execution fails
+
+```bash
+# Check file permissions
+ls -la tasks/scripts/category/script.ts
+
+# Make executable if needed
+chmod +x tasks/scripts/category/script.ts
+
+# Run script directly to see errors
+bun run tasks/scripts/category/script.ts
+```
+
+### 1Password tasks fail
+
+```bash
+# Check 1Password CLI is installed
+which op
+op --version
+
+# Verify authentication
+op account list
+
+# Sign in if needed
+op signin
+```
+
+---
+
+## Related Documentation
+
+- [Main README](../README.md) - Project overview
+- [CONTRIBUTING](../CONTRIBUTING.md) - Development guidelines
+- [Installation Guide](../docs/installer.md) - AI Toolkit usage
+- [1Password Integration](../docs/1password.md) - Secret management setup
+- [CLAUDE.md](../CLAUDE.md) - Project instructions for Claude Code
+
+---
+
+**Need help?** Run `task` to see all available task categories, or `task <category>` to see category-specific tasks.