feat: Sync upstream template improvements

.ai/commands/README.md

@@ -0,0 +1,108 @@
+# AI Commands for Agentic Workflow Template
+
+This directory contains helpful commands for working with the agentic workflow template. These commands provide
+quick access to common tasks and workflows and can be used by any AI assistant.
+
+## Available Commands
+
+### Setup & Configuration
+
+- **[setup-project.md](setup-project.md)** - Initial project setup and configuration
+- **[label-management.md](label-management.md)** - GitHub label setup and management
+- **[update-template.md](update-template.md)** - Sync with latest template updates
+
+### Development
+
+- **[create-issue.md](create-issue.md)** - Create GitHub issues with optional AI automation
+- **[create-ai-task.md](create-ai-task.md)** - Execute AI tasks locally or via GitHub
+- **[development-workflow.md](development-workflow.md)** - Standard development commands
+- **[run-tests.md](run-tests.md)** - Testing commands and strategies
+
+### Operations
+
+- **[workflow-management.md](workflow-management.md)** - GitHub Actions workflow management
+- **[security-checks.md](security-checks.md)** - Security scanning and validation
+- **[cost-monitoring.md](cost-monitoring.md)** - Monitor and control AI API costs
+
+### Documentation & Analysis
+
+- **[roadmap.sh](../../shared-commands/commands/roadmap.sh)** - View and generate project roadmaps.
+- **[create-spec-issue.sh](../../shared-commands/commands/create-spec-issue.sh)** - Create detailed technical
+  specifications.
+- **[analyze-issue.sh](../../shared-commands/commands/analyze-issue.sh)** - Analyze GitHub issues for
+  requirements and complexity.
+
+### Support
+
+- **[troubleshooting.md](troubleshooting.md)** - Common issues and solutions
+
+## Quick Start
+
+1. **Initial Setup**
+
+   ```bash
+   # See setup-project.md
+   ./install.sh && source venv/bin/activate
+   ```
+
+2. **Create Issues & AI Tasks**
+
+   ```bash
+   # Create issue (see create-issue.md)
+   npx @stillrivercode/shared-commands create-issue -t "Fix login bug" -b "Description here"
+
+   # Create issue with AI automation (explicit opt-in)
+   npx @stillrivercode/shared-commands create-issue -t "Add feature" --ai-task -b "Details here"
+
+   # Execute AI task for existing issue (see create-ai-task.md)
+   ./scripts/execute-ai-task.sh ISSUE_NUMBER
+   ```
+
+3. **Generate Documentation** (using unified shared commands)
+
+   ```bash
+   # Create technical specification
+   npx @stillrivercode/shared-commands create-spec-issue --title "Authentication Architecture"
+
+   # Analyze existing issue for requirements and complexity
+   npx @stillrivercode/shared-commands analyze-issue --issue 25
+   ```
+
+4. **Run Tests**
+
+   ```bash
+   # See run-tests.md
+   pytest
+   ```
+
+## Shared Commands
+
+The core commands for this workflow are located in the `shared-commands/`
+directory and distributed as an NPM package for consistency across different AI assistants (Claude, Gemini, etc.).
+
+### Using Shared Commands
+
+```bash
+# Use commands directly via npx
+npx @stillrivercode/shared-commands roadmap
+npx @stillrivercode/shared-commands create-spec-issue --title "Technical Design"
+npx @stillrivercode/shared-commands analyze-issue --issue 25
+```
+
+## Command Usage
+
+Each command file contains:
+
+- Purpose and description
+- Actual commands to run
+- Examples and use cases
+- Related documentation
+
+## Contributing
+
+When adding new commands:
+
+1. Create a descriptive `.md` file
+2. Include clear examples
+3. Link to relevant documentation
+4. Update this README

.ai/commands/cost-monitoring.md

@@ -0,0 +1,47 @@
+# Cost Monitoring
+
+Monitor and analyze AI API costs.
+
+## Cost Analysis
+
+```bash
+# View cost analysis documentation
+cat docs/cost-analysis.md
+
+# Check estimated costs for different usage patterns
+grep -A10 "Estimated Costs" README.md
+```
+
+## Cost Tracking Templates
+
+```bash
+# Copy cost monitoring template
+cp docs/templates/ai-cost-monitoring-template.csv my-costs.csv
+
+# View Google Sheets template guide
+cat docs/templates/cost-monitoring-guide.md
+```
+
+## Usage Patterns
+
+```bash
+# Light usage (10-20 tasks/month): $20-50
+# Moderate usage (50-100 tasks/month): $75-200
+# Heavy usage (100+ tasks/month): $150-500
+
+# Cost factors:
+# - Issue complexity
+# - Code generation amount
+# - Number of iterations
+# - Model selection (Claude Sonnet)
+```
+
+## Cost Reduction Tips
+
+```bash
+# 1. Use specific, clear issue descriptions
+# 2. Break large features into smaller tasks
+# 3. Set spending limits in workflow config
+# 4. Use ai-task-small label for simple tasks
+# 5. Monitor logs: gh run list --workflow=ai-task.yml
+```

.ai/commands/create-ai-task.md

@@ -0,0 +1,30 @@
+# Create AI Task
+
+Execute an AI task locally (useful for testing before GitHub workflow).
+
+## Command
+
+```bash
+# Execute AI task for a specific issue
+./scripts/execute-ai-task.sh ISSUE_NUMBER
+
+# Example with real issue number
+./scripts/execute-ai-task.sh 42
+```
+
+## Manual Process
+
+```bash
+# 1. Create feature branch
+git checkout -b feature/ai-task-ISSUE_NUMBER
+
+# 2. Run Claude with issue context
+claude "Implement the requirements from GitHub issue #ISSUE_NUMBER"
+
+# 3. Create PR when done
+./scripts/create-pr.sh
+```
+
+## GitHub Workflow
+
+Alternatively, add `ai-task` label to any GitHub issue to trigger automated implementation.

.ai/commands/create-issue.md

@@ -0,0 +1,200 @@
+# Create Issue Command
+
+Create GitHub issues with optional labels and automation triggers. The `ai-task` label is **NOT** automatically added.
+
+## Features
+
+- **Manual Label Control**: No automatic `ai-task` label addition
+- **Interactive Mode**: Guided issue creation with prompts
+- **Label Validation**: Warns about non-existent labels
+- **Dry Run Mode**: Preview before creation
+- **Prerequisite Validation**: Checks GitHub CLI and authentication
+- **AI Integration**: Optional explicit opt-in for AI workflows
+
+## Usage Examples
+
+```bash
+# Basic issue creation
+npx @stillrivercode/shared-commands create-issue -t "Fix login bug" -b "Users cannot log in with valid credentials"
+
+# Issue with labels (manual ai-task)
+npx @stillrivercode/shared-commands create-issue -t "Add user auth" -l "feature,backend" -b "Implement JWT authentication"
+
+# Explicit AI task (opt-in required)
+npx @stillrivercode/shared-commands create-issue -t "Refactor database layer" --ai-task -b "Clean up database connections"
+
+# Interactive mode for guided creation
+npx @stillrivercode/shared-commands create-issue -i
+
+# Dry run to preview without creating
+npx @stillrivercode/shared-commands create-issue -t "Test issue" --dry-run
+
+# Full example with all options
+npx @stillrivercode/shared-commands create-issue \
+  -t "Implement user dashboard" \
+  -b "Create responsive user dashboard with analytics" \
+  -l "feature,frontend,priority-high" \
+  -a "developer-username" \
+  --ai-task
+```
+
+## Command Options
+
+### Required
+
+- `-t, --title TITLE` - Issue title (required)
+
+### Optional
+
+- `-b, --body BODY` - Issue description/body
+- `-l, --labels LABELS` - Comma-separated labels
+- `-a, --assignee USER` - Assign to GitHub user
+- `-m, --milestone NUMBER` - Milestone number
+- `--ai-task` - **Explicit opt-in** to add ai-task label
+- `--dry-run` - Preview without creating
+- `-i, --interactive` - Interactive guided mode
+- `-h, --help` - Show help information
+
+## Label Categories
+
+### Standard Labels
+
+- `feature`, `bug`, `enhancement`, `documentation`, `question`
+- `good-first-issue`, `help-wanted`
+
+### Priority Labels
+
+- `priority-high`, `priority-medium`, `priority-low`
+
+### AI Workflow Labels (Manual Opt-in)
+
+- `ai-task` - General AI development tasks
+- `ai-bug-fix` - AI-assisted bug fixes
+- `ai-refactor` - Code refactoring requests
+- `ai-test` - Test generation
+- `ai-docs` - Documentation updates
+
+### Technical Area Labels
+
+- `backend`, `frontend`, `api`, `database`, `security`
+
+## AI Task Integration
+
+### Manual Opt-in Required
+
+The script **does not** automatically add the `ai-task` label. Users must:
+
+1. **Explicitly use `--ai-task` flag**
+2. **Include `ai-task` in `--labels` list**
+3. **Choose to add it in interactive mode**
+
+### AI Workflow Trigger
+
+When `ai-task` label is explicitly added:
+
+- Triggers automated AI implementation workflow
+- Creates feature branch automatically
+- Generates pull request with implementation
+- Estimated timeline: 5-15 minutes
+
+## Interactive Mode
+
+The interactive mode provides guided issue creation:
+
+```bash
+./scripts/create-issue.sh -i
+```
+
+Interactive flow:
+
+1. **Title prompt** - Required field
+2. **Description input** - Multi-line or editor support
+3. **Label selection** - Suggestions provided
+4. **AI task confirmation** - Explicit yes/no for ai-task label
+5. **Assignee selection** - Optional
+6. **Preview and confirmation** - Review before creation
+
+## Prerequisites
+
+- **GitHub CLI (gh)** - Must be installed and authenticated
+- **Git repository** - Must be run from within a git repo
+- **Issues enabled** - Repository must have Issues feature enabled
+
+## Validation and Safety
+
+### Input Validation
+
+- Title is required and validated
+- GitHub CLI authentication checked
+- Repository Issues feature verified
+- Label existence warnings (but doesn't block)
+
+### Security Features
+
+- No automatic label addition
+- Explicit user consent for AI workflows
+- Dry run mode for safe testing
+- Clear warnings about AI trigger implications
+
+## Output Examples
+
+### Successful Creation
+
+```text
+✅ Issue created successfully!
+   URL: https://github.com/user/repo/issues/42
+   Issue #: 42
+
+🤖 AI Task Workflow:
+   The ai-task label will trigger automated AI implementation
+   Monitor progress in the Actions tab of your repository
+   Expected timeline: 5-15 minutes for implementation
+
+🌐 Open issue in browser? (Y/n):
+```
+
+### Dry Run Preview
+
+```text
+🔍 DRY RUN - Would execute:
+   gh issue create --title "Test Feature" --label "feature ai-task"
+
+📋 Issue Details:
+   Title: Test Feature
+   Labels: feature,ai-task
+   Assignee: none
+   Milestone: none
+
+   Body:
+   -----
+   Implement new test feature with proper error handling
+```
+
+## Best Practices
+
+1. **Use descriptive titles** - Clear, specific issue titles
+2. **Provide detailed descriptions** - Include requirements and context
+3. **Choose appropriate labels** - Use existing label conventions
+4. **Consider AI implications** - Only use `--ai-task` when you want automated implementation
+5. **Test with dry run** - Preview complex issues before creation
+6. **Use interactive mode** - For comprehensive issue creation
+
+## Integration with Existing Workflows
+
+This command integrates with:
+
+- **AI task workflows** - When ai-task label is explicitly added
+- **Project management** - Milestone and assignee support
+- **Label management** - Respects existing repository labels
+- **User story tracking** - Can create issues for user story implementation
+
+## Error Handling
+
+Common errors and solutions:
+
+- **GitHub CLI not authenticated** - Run `gh auth login`
+- **Issues disabled** - Enable Issues in repository settings
+- **Invalid assignee** - Check GitHub username spelling
+- **Network issues** - Check internet connection and GitHub status
+
+This command provides safe, controlled issue creation with explicit opt-in for AI automation workflows.