@northbridge-security/secureai 0.1.13

package/docs/guides/agents.gotask.md

@@ -0,0 +1,1037 @@
+# GoTask Usage Guide for AI Agents
+
+## Purpose
+
+This guide provides AI agents with best practices for working with GoTask (Task) task automation in operator repositories. Use this when creating, modifying, or executing tasks defined in Taskfile.yml.
+
+## Target Audience
+
+AI agents (Claude Code, Cursor, Copilot, etc.) working with projects that use GoTask for task automation and build orchestration.
+
+## Core Principles
+
+### 1. Task Discovery First
+
+Always check existing tasks before creating new ones:
+
+````bash
+# List all available tasks
+task --list
+
+# View tasks in specific namespace
+task gotask
+task yaml
+task claude
+```text
+
+### 2. Use Existing Utilities
+
+The `task gotask` namespace provides utilities for task development:
+
+**Task Development:**
+
+- `task gotask:new:task` - Create new task interactively
+- `task gotask:new:script` - Create TypeScript task script
+- `task gotask:validate` - Validate Taskfile syntax
+- `task gotask:format` - Format default task output
+
+**Templates:**
+
+- `task gotask:template:basic` - Basic task template
+- `task gotask:template:build` - Build task template
+- `task gotask:template:test` - Test task template
+
+**Documentation:**
+
+- `task gotask:docs:generate` - Generate documentation
+- `task gotask:docs:view` - View best practices
+- `task gotask:docs:edit` - Edit best practices
+
+### 3. Prefer Scripts Over Inline Commands
+
+**❌ Bad - Complex bash in taskfile:**
+
+```yaml
+tasks:
+  lint:
+    cmds:
+      - |
+        if command -v prettier &> /dev/null; then
+          FILES=$(find . -name "*.yml" -not -path "*/node_modules/*")
+          for file in $FILES; do
+            prettier --check "$file" || exit 1
+          done
+        else
+          echo "prettier not found"
+          exit 1
+        fi
+```text
+
+**✅ Good - Delegate to TypeScript:**
+
+```yaml
+tasks:
+  lint:
+    desc: 'Lint YAML files'
+    cmds:
+      - bun run ./src/tasks/yaml/lint.ts
+    env:
+      FILES: '{{.FILES | default "*.yml"}}'
+```text
+
+## Parameter Syntax Standards
+
+### Preferred: Shell-Style Parameters
+
+**Long format (recommended):**
+
+```bash
+task yaml:lint --files="*.yml"
+task yaml:lint --linter=prettier
+task build --target=production
+```text
+
+**Short format (for aliases):**
+
+```bash
+task yaml:lint -f="*.yml"
+task yaml:lint -l=prettier
+task build -t=production
+```text
+
+**Positional (single parameter):**
+
+```bash
+task yaml:lint -- *.yml
+task test -- unit
+```text
+
+### Legacy: Environment Variable Style
+
+**⚠️  Backward compatible but not preferred:**
+
+```bash
+# Still works but avoid in new code
+task yaml:lint FILES="*.yml"
+task build TARGET=production
+```text
+
+### Implementation in Taskfile
+
+Define parameters using GoTask variables:
+
+```yaml
+tasks:
+  lint:
+    desc: 'Lint files with optional pattern'
+    vars:
+      PATTERN: '{{.files | default "*.yml"}}'  # Map --files flag
+      LINTER: '{{.linter | default "auto"}}'   # Map --linter flag
+    cmds:
+      - bun run ./scripts/lint.ts
+    env:
+      FILES: '{{.PATTERN}}'
+      LINTER: '{{.LINTER}}'
+```text
+
+Usage:
+
+```bash
+# Shell-style (preferred)
+task lint --files="src/**/*.yml" --linter=prettier
+
+# Legacy (supported)
+task lint FILES="src/**/*.yml" LINTER=prettier
+```text
+
+## Task Structure Best Practices
+
+### 1. Namespace Organization
+
+```yaml
+# Main Taskfile.yml
+version: '3'
+
+includes:
+  yaml:
+    taskfile: ./tasks/yaml.yml
+    dir: .
+
+  claude:
+    taskfile: ./tasks/claude.yml
+    dir: .
+
+  gotask:
+    taskfile: ./tasks/gotask.yml
+    dir: .
+```text
+
+### 2. Task Definition Pattern
+
+```yaml
+version: '3'
+
+vars:
+  DEFAULT_PATTERN: "*.yml,*.yaml"
+
+tasks:
+  default:
+    desc: 'Show available tasks'
+    aliases: [help, h]
+    silent: true
+    cmds:
+      - |
+        echo "Task Category Name"
+        echo "Command                  Alias    Description"
+        echo "─────────────────────────────────────────────"
+        echo "task category:action     a        Description"
+
+  action:
+    desc: 'Task description'
+    aliases: [a]
+    silent: true
+    vars:
+      PARAM: '{{.param | default .DEFAULT_PATTERN}}'
+    cmds:
+      - bun run ./src/tasks/category/action.ts
+    env:
+      PARAMETER_NAME: '{{.PARAM}}'
+```text
+
+### 3. Default Task Help
+
+Every task file should have a `default` task showing available commands:
+
+```yaml
+tasks:
+  default:
+    desc: 'Show available YAML tasks'
+    aliases: [help, h]
+    silent: true
+    cmds:
+      - |
+        # Use color codes for better readability
+        GREEN='\033[0;32m'
+        YELLOW='\033[0;33m'
+        BOLD='\033[1m'
+        NC='\033[0m'
+
+        echo -e "${BOLD}Category Name${NC}"
+        echo ""
+        echo -e "Command                  Alias    Description"
+        echo "─────────────────────────────────────────────"
+        echo -e "${GREEN}task cat:action${NC}      ${YELLOW}a${NC}        Do something"
+```text
+
+## Table Formatting with Colors
+
+### The Challenge
+
+Creating aligned tables with ANSI color codes is challenging because:
+
+1. **`printf` with width specifiers** counts escape sequences as part of string length
+2. **`column -t`** doesn't understand ANSI codes and escapes them
+3. Manual spacing with `echo -e` is fragile and breaks easily
+
+### Recommended Solution: Manual Spacing with `echo -e`
+
+Use `echo -e` with careful manual spacing. This is the **only reliable method** that preserves colors.
+
+**Example:**
+
+```yaml
+tasks:
+  default:
+    desc: 'Show available tasks'
+    silent: true
+    cmds:
+      - |
+        GREEN='\033[0;32m'
+        YELLOW='\033[0;33m'
+        BLUE='\033[0;34m'
+        BOLD='\033[1m'
+        NC='\033[0m'
+
+        echo -e "${BOLD}Project Name${NC}"
+        echo ""
+        echo "Command                            Alias     Description                              Examples"
+        echo "───────────────────────────────────────────────────────────────────────────────────────────────────"
+        echo -e "${BOLD}Core Tasks:${NC}"
+        echo -e "  ${GREEN}task build${NC}                       ${YELLOW}b${NC}         Build the project"
+        echo -e "  ${GREEN}task test${NC}                        ${YELLOW}t${NC}         Run tests"
+        echo -e "  ${GREEN}task lint${NC}                        ${YELLOW}l${NC}         Run linter                               FILES=\"...\""
+```text
+
+### Column Spacing Guidelines
+
+**Standard column widths:**
+
+- **Command**: ~35 characters (including indentation)
+- **Alias**: ~10 characters
+- **Description**: ~40 characters
+- **Examples**: Flexible (remaining space)
+
+**Tips:**
+
+1. **Use a monospaced font** when editing to visually align columns
+2. **Count visible characters only** (ignore ANSI escape codes mentally)
+3. **Test with `task`** - run the task to see actual output
+4. **Remove empty examples** - Don't use `--` or placeholders for commands without examples
+5. **Abbreviate long examples** - Use `"..."` for path patterns instead of full paths
+
+**Example spacing breakdown:**
+
+```bash
+# Each section is aligned by counting visible characters
+#         Command (35 chars)     Alias(10)  Description (40 chars)             Examples
+echo -e "  ${GREEN}task build${NC}                       ${YELLOW}b${NC}         Build the project"
+#         ^^indentation
+#           ^^^^ ^^^^^ = task build (10 chars)
+#                      ^^^^^^^^^^^^^^^ = spaces to reach column 2 (35 - 10 - 2 indent = 23 spaces)
+#                                     ^ = b (1 char)
+#                                       ^^^^^^^^^ = spaces to reach column 3 (10 - 1 = 9 spaces)
+#                                                 ^^^^^^^^^^^^^^^^^^^ = description text
+```text
+
+### What NOT to Do
+
+**❌ Using `column -t` with colors:**
+
+```yaml
+# This BREAKS colors - escape codes are treated as text
+{
+  printf "%s|%s|%s\n" "${GREEN}task build${NC}" "${YELLOW}b${NC}" "Build"
+} | column -t -s '|'
+# Output: \033[0;32mtask build\033[0m  \033[0;33mb\033[0m  Build
+```text
+
+**❌ Using `printf` with width specifiers:**
+
+```yaml
+# This BREAKS alignment - counts escape codes in width
+printf "  %-35s  %-10s  %s\n" "${GREEN}task build${NC}" "${YELLOW}b${NC}" "Build"
+# The color codes add ~20 characters, making alignment wrong
+```text
+
+**✅ Correct approach:**
+
+```yaml
+# Manual spacing with echo -e
+echo -e "  ${GREEN}task build${NC}                       ${YELLOW}b${NC}         Build the project"
+```text
+
+### Testing Your Table
+
+Always test by running the task:
+
+```bash
+task category:help
+# or
+task category
+```text
+
+Look for:
+
+- Misaligned columns
+- Color codes appearing as text (escape sequences visible)
+- Inconsistent spacing between rows
+
+## Creating New Tasks
+
+### Option 1: Use Interactive Creator
+
+```bash
+# Let the utility guide you
+task gotask:new:task
+
+# Creates task with proper structure
+# Prompts for: name, description, aliases, commands
+```text
+
+### Option 2: Use Templates
+
+```bash
+# Generate template and modify
+task gotask:template:basic > tasks/new-category.yml
+
+# Edit the generated template
+# Include in main Taskfile.yml
+```text
+
+### Option 3: Manual Creation
+
+Follow this checklist:
+
+1. **Create task file** - `tasks/category.yml`
+2. **Define structure** - version, vars, tasks
+3. **Add default task** - Help output with color codes
+4. **Define actions** - With descriptions and aliases
+5. **Delegate to scripts** - TypeScript in `src/tasks/category/`
+6. **Include in main** - Add to `Taskfile.yml` includes
+7. **Validate syntax** - `task gotask:validate`
+8. **Update docs** - Add section to `tasks/README.md`
+
+## TypeScript Task Scripts
+
+### Directory Structure
+
+```text
+src/tasks/category/
+├── types.ts          # Type definitions
+├── utils.ts          # Helper functions
+├── action1.ts        # Executable script
+├── action2.ts        # Executable script
+└── action3.ts        # Executable script
+
+tests/tasks/category/
+├── utils.test.ts     # Unit tests
+├── action1.test.ts   # Unit tests
+└── integration.test.ts
+```text
+
+### Script Template
+
+```typescript
+#!/usr/bin/env bun
+
+/**
+ * Copyright (c) 2024-2025 Company Name
+ * All rights reserved.
+ */
+
+import { execSync } from 'node:child_process';
+import type { ResultType } from './types';
+import { helperFunction } from './utils';
+
+/**
+ * Main script function
+ */
+function main(): void {
+  console.log('🔧 Starting action...\n');
+
+  // Get parameters from environment
+  const param = process.env.PARAM || 'default';
+
+  try {
+    // Implementation
+    const result = helperFunction(param);
+
+    console.log('✅ Action complete');
+    process.exit(0);
+  } catch (error) {
+    console.error('❌ Action failed:', error);
+    process.exit(1);
+  }
+}
+
+// Run if executed directly
+if (import.meta.main) {
+  main();
+}
+
+export { main };
+```text
+
+## Clean Output Standards
+
+### Principle: Only Print What Changes
+
+Tasks should follow a minimal output philosophy - only show information when something changes or when reporting final results. Avoid verbose progress messages, status updates, or unnecessary confirmations.
+
+**Key rules:**
+
+1. **Silent on success** - If everything works as expected, don't print status messages
+2. **Show final result** - Print one line showing what happened and the outcome
+3. **Error to stderr** - All error messages go to stderr with `>&2`
+4. **Use color codes** - Green checkmark for success, red X for errors, yellow for warnings
+5. **Include URLs** - Make output actionable by including clickable links
+
+### Output Format Pattern
+
+**Success format:**
+
+```bash
+echo -e "${GREEN}✓${NC} Action: result/URL"
+```
+
+**Error format:**
+
+```bash
+echo -e "${RED}❌ Error description${NC}" >&2
+exit 1
+```
+
+**Warning format:**
+
+```bash
+echo -e "${YELLOW}⚠${NC} Warning: fallback action"
+```
+
+### Examples
+
+**❌ Bad - Verbose output:**
+
+```yaml
+tasks:
+  pr:create:
+    cmds:
+      - |
+        echo "Starting PR creation process..."
+        echo "Getting current branch..."
+        BRANCH=$(git branch --show-current)
+        echo "Current branch: $BRANCH"
+
+        echo "Checking for existing PR..."
+        PR=$(gh pr list --head "$BRANCH" --json number -q '.[0].number')
+
+        if [ -n "$PR" ]; then
+          echo "Found existing PR #$PR"
+          echo "Updating PR title and body..."
+          gh pr edit "$PR" --title "$TITLE" --body "$BODY"
+          echo "PR updated successfully!"
+          echo "PR URL: https://github.com/owner/repo/pull/$PR"
+        fi
+```
+
+Output:
+```
+Starting PR creation process...
+Getting current branch...
+Current branch: feat/new-feature
+Checking for existing PR...
+Found existing PR #123
+Updating PR title and body...
+https://github.com/owner/repo/pull/123
+PR updated successfully!
+PR URL: https://github.com/owner/repo/pull/123
+```
+
+**✅ Good - Clean output:**
+
+```yaml
+tasks:
+  pr:create:
+    cmds:
+      - |
+        GREEN='\033[0;32m'
+        NC='\033[0m'
+
+        BRANCH=$(git branch --show-current)
+        PR=$(gh pr list --head "$BRANCH" --json number -q '.[0].number')
+
+        if [ -n "$PR" ]; then
+          gh pr edit "$PR" --title "$TITLE" --body "$BODY" &>/dev/null
+          PR_URL=$(gh pr view "$PR" --json url -q '.url')
+          echo -e "${GREEN}✓${NC} Updated: $PR_URL"
+        fi
+```
+
+Output:
+```
+✓ Updated: https://github.com/owner/repo/pull/123
+```
+
+### Multi-Step Tasks
+
+For tasks with multiple steps, show one status line per significant change:
+
+**Example: PR creation with push**
+
+```yaml
+tasks:
+  pr:create:
+    cmds:
+      - |
+        GREEN='\033[0;32m'
+        YELLOW='\033[0;33m'
+        NC='\033[0m'
+
+        # Extract title
+        TITLE=$(head -n1 .pr.local.md)
+        echo -e "${GREEN}✓${NC} Title: $TITLE"
+
+        # Push branch
+        if git push -u origin "$BRANCH" &>/dev/null; then
+          echo -e "${GREEN}✓${NC} Branch pushed to origin/$BRANCH"
+        else
+          echo -e "${YELLOW}⚠${NC} Git push failed (will use gh CLI)"
+        fi
+
+        # Create or update PR
+        if [ -n "$EXISTING_PR" ]; then
+          gh pr edit "$EXISTING_PR" --title "$TITLE" --body "$BODY" &>/dev/null
+          echo -e "${GREEN}✓${NC} Updated: $PR_URL"
+        else
+          PR_URL=$(gh pr create --title "$TITLE" --body "$BODY" --draft)
+          echo -e "${GREEN}✓${NC} Created: $PR_URL"
+        fi
+```
+
+Output:
+```
+✓ Title: feat(cli): add new command
+✓ Branch pushed to origin/feat/new-command
+✓ Created: https://github.com/owner/repo/pull/124
+```
+
+### Suppressing Command Output
+
+Use output redirection to hide verbose command output:
+
+**Redirect stderr only:**
+
+```bash
+git push -u origin "$BRANCH" 2>/dev/null
+```
+
+**Redirect both stdout and stderr:**
+
+```bash
+git push -u origin "$BRANCH" &>/dev/null
+gh pr edit "$PR" --title "$TITLE" &>/dev/null
+```
+
+**Capture output for conditional display:**
+
+```bash
+OUTPUT=$(command 2>&1)
+if [ $? -ne 0 ]; then
+  echo "$OUTPUT" >&2
+  exit 1
+fi
+```
+
+### Color Code Standards
+
+Define color codes at the start of each task:
+
+```bash
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+RED='\033[0;31m'
+CYAN='\033[0;36m'
+BOLD='\033[1m'
+NC='\033[0m'  # No Color
+```
+
+**Usage:**
+
+- `GREEN` - Success messages, checkmarks
+- `RED` - Errors, failures
+- `YELLOW` - Warnings, fallback actions
+- `CYAN` - Informational (use sparingly)
+- `BOLD` - Headers (help menus only)
+
+### Error Messages
+
+Error messages should be:
+
+1. **Specific** - Say exactly what went wrong
+2. **Actionable** - Suggest how to fix it
+3. **Concise** - One or two lines maximum
+
+**Example:**
+
+```bash
+if [ -z "$GITHUB_TOKEN" ]; then
+  echo -e "${RED}❌ GitHub token not found${NC}" >&2
+  echo "Set GITHUB_TOKEN in .env" >&2
+  exit 1
+fi
+```
+
+### Summary Output
+
+For tasks that retrieve or process data, show a single summary line:
+
+**❌ Bad:**
+
+```bash
+echo "Comments retrieved successfully!"
+echo ""
+echo "Summary:"
+echo "  General comments: 5"
+echo "  Code review comments: 12"
+echo "  Reviews: 3"
+echo "  Total: 20"
+echo ""
+echo "Log saved to: /path/to/log.txt"
+echo ""
+echo "View with: cat /path/to/log.txt"
+```
+
+**✅ Good:**
+
+```bash
+echo -e "${GREEN}✓${NC} Retrieved 20 comments for PR #123 → /path/to/log.txt"
+```
+
+## Common Patterns
+
+### 1. File Pattern Discovery
+
+```typescript
+// src/tasks/category/utils.ts
+export function discoverFiles(patterns: string[]): string[] {
+  const files = new Set<string>();
+
+  for (const pattern of patterns) {
+    if (pattern.includes('**')) {
+      // Recursive glob
+      const found = findFilesRecursive(baseDir, filename);
+      found.forEach(f => files.add(f));
+    } else {
+      // Simple pattern via shell
+      const matched = execSync('ls ' + pattern, {
+        encoding: 'utf-8',
+        shell: '/bin/bash'
+      }).trim().split('\n');
+      matched.forEach(f => files.add(f));
+    }
+  }
+
+  return Array.from(files).sort();
+}
+```text
+
+### 2. Tool Detection
+
+```typescript
+// src/tasks/category/utils.ts
+export function commandExists(command: string): boolean {
+  try {
+    execSync('command -v ' + command, { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function detectTools() {
+  return {
+    tool1: commandExists('tool1'),
+    tool2: commandExists('tool2'),
+    npm: commandExists('npm'),
+  };
+}
+```text
+
+### 3. Environment Variable Handling
+
+```typescript
+// Get from environment with defaults
+const pattern = process.env.FILES || '*.yml,*.yaml';
+const linter = process.env.LINTER || 'auto';
+
+// Parse patterns
+const patterns = pattern.split(',').map(p => p.trim());
+```text
+
+### 4. Exit Codes
+
+```typescript
+// Success
+process.exit(0);
+
+// Failure
+process.exit(1);
+
+// Usage error
+process.exit(2);
+```text
+
+### 5. Quiet Output on Success
+
+**Best Practice**: Tasks should be quiet when no issues are found and provide a `VERBOSE` flag for detailed output.
+
+```typescript
+// src/tasks/category/action.ts
+function main(): void {
+  const verbose = process.env.VERBOSE === 'true' || process.env.VERBOSE === '1';
+
+  if (verbose) {
+    console.log('🔧 Starting action...\n');
+  }
+
+  // Perform checks
+  const result = performAction();
+
+  // Only output when there are issues OR in verbose mode
+  if (!result.success) {
+    console.log('❌ Action failed:\n');
+    result.errors.forEach(err => console.log('  ' + err));
+    process.exit(1);
+  } else {
+    if (verbose) {
+      console.log('✅ Action completed successfully');
+    }
+    process.exit(0);
+  }
+}
+```text
+
+**Taskfile Configuration**:
+
+```yaml
+tasks:
+  action:
+    desc: 'Perform action (quiet on success, use VERBOSE=1 for details)'
+    vars:
+      VERBOSE_FLAG: '{{.VERBOSE | default ""}}'
+    cmds:
+      - bun run ./src/tasks/category/action.ts
+    env:
+      VERBOSE: '{{.VERBOSE_FLAG}}'
+```text
+
+**Usage**:
+
+```bash
+task category:action              # Quiet on success
+VERBOSE=1 task category:action    # Show all output
+```text
+
+**Why**: This pattern reduces noise in CI/CD pipelines and local development while still allowing detailed output when needed for debugging.
+
+## Validation and Testing
+
+### Before Committing
+
+```bash
+# Validate Taskfile syntax
+task gotask:validate
+
+# Run affected tests
+bun test tests/tasks/category/
+
+# Check task works
+task category:action -- test-value
+```text
+
+### Test Structure
+
+```typescript
+import { describe, expect, it, mock } from 'bun:test';
+import { helperFunction } from '../../../src/tasks/category/utils';
+
+describe('category utils', () => {
+  it('should process input correctly', () => {
+    const result = helperFunction('input');
+    expect(result).toBeDefined();
+  });
+});
+```text
+
+## Documentation Requirements
+
+### 1. Task File Comments
+
+```yaml
+# YAML Linting & Validation Tasks
+# Provides YAML validation, linting, and auto-fixing for all YAML files.
+
+version: '3'
+```text
+
+### 2. README.md Section
+
+Add to `tasks/README.md`:
+
+```markdown
+### Category Name ([category.yml](category.yml))
+
+Brief description of what this task category provides.
+
+**Commands:**
+
+| Task                    | Alias | Description              |
+| ----------------------- | ----- | ------------------------ |
+| `task cat:action`       | `a`   | Do something             |
+| `task cat:other`        | `o`   | Do something else        |
+
+**Usage:**
+
+\`\`\`bash
+# Example command
+task cat:action --param="value"
+
+# With short alias
+task cat:action -p="value"
+\`\`\`
+```text
+
+### 3. JSDoc Comments
+
+```typescript
+/**
+ * Process files matching pattern
+ *
+ * @param pattern - Glob pattern to match
+ * @param options - Processing options
+ * @returns Array of processed file paths
+ *
+ * @example
+ * ```typescript
+ * const files = processFiles('*.yml', { exclude: ['node_modules'] });
+ * ```
+ */
+export function processFiles(
+  pattern: string,
+  options: ProcessOptions
+): string[] {
+  // Implementation
+}
+```text
+
+## Troubleshooting
+
+### Task Not Found
+
+```bash
+# Check if task exists
+task --list | grep task-name
+
+# Verify include in main Taskfile
+grep "includes:" Taskfile.yml
+
+# Check task file exists
+ls tasks/category.yml
+```text
+
+### Script Not Executing
+
+```bash
+# Check permissions
+ls -la src/tasks/category/script.ts
+
+# Make executable
+chmod +x src/tasks/category/script.ts
+
+# Run directly to see errors
+bun run src/tasks/category/script.ts
+```text
+
+### Parameter Not Working
+
+```bash
+# Check variable mapping in task
+cat tasks/category.yml | grep -A5 "vars:"
+
+# Try with quotes
+task category:action --param="value with spaces"
+
+# Check environment in script
+bun run -e 'console.log(process.env)' src/tasks/category/script.ts
+```text
+
+## When to Use GoTask
+
+### ✅ Good Use Cases
+
+- Build automation
+- Development workflows
+- CI/CD orchestration
+- Linting and validation
+- Testing pipelines
+- Code generation
+- Setup and initialization
+- Multi-step processes
+
+### ❌ Not Recommended
+
+- Runtime application logic
+- Web servers (use proper frameworks)
+- Database migrations (use dedicated tools)
+- Complex business logic (use application code)
+
+## Integration with Other Tools
+
+### Git Hooks
+
+```yaml
+tasks:
+  pre-commit:
+    desc: 'Run pre-commit checks'
+    cmds:
+      - task lint
+      - task typecheck
+      - task test
+```text
+
+### CI/CD
+
+```yaml
+tasks:
+  ci:
+    desc: 'Run CI checks'
+    cmds:
+      - task lint
+      - task typecheck
+      - task test
+      - task build
+      - task semgrep
+```text
+
+### IDE Integration
+
+Most IDEs can run GoTask tasks:
+
+- VSCode: Install "Task" extension
+- Cursor: Built-in terminal support
+- IntelliJ: Configure as External Tool
+
+## Quick Reference
+
+### Essential Commands
+
+```bash
+# List all tasks
+task --list
+
+# Run task
+task category:action
+
+# With parameters (preferred)
+task category:action --param="value"
+
+# Legacy style (supported)
+task category:action PARAM="value"
+
+# View task help
+task category
+
+# Validate taskfiles
+task gotask:validate
+
+# Create new task
+task gotask:new:task
+```text
+
+### File Locations
+
+```text
+Taskfile.yml           # Main task runner
+tasks/                 # Task definitions
+  category.yml         # Category-specific tasks
+  README.md            # Task documentation
+src/tasks/             # TypeScript implementations
+  category/            # Category scripts
+    types.ts
+    utils.ts
+    action.ts
+tests/tasks/           # Unit tests
+  category/
+    utils.test.ts
+```text
+
+## Related Documentation
+
+- [tasks/README.md](../../tasks/README.md) - Complete task library reference
+- [docs/guides/agents.markdown.md](./agents.markdown.md) - Markdown formatting standards
+- [CLAUDE.md](../../CLAUDE.md) - Project instructions for Claude Code
+- [GoTask Documentation](https://taskfile.dev) - Official GoTask docs
+
+---
+
+**For AI Agents:** Use this guide when working with GoTask tasks. Always check existing tasks before creating new ones, delegate complex logic to TypeScript, and follow the parameter syntax standards. Use `task gotask` utilities to streamline task development.
+````