Standardize workflow documentation structure with template and enhanced examples

examples/workflows/README.md

@@ -0,0 +1,61 @@
+# 📚 Example Workflows
+
+This directory contains example GitHub Agentic Workflows with comprehensive documentation.
+
+## 📖 Using These Examples
+
+Each workflow includes standardized documentation to help you understand, install, and customize it:
+
+- **README.md** - Overview, use cases, and key features
+- **SETUP.md** - Step-by-step installation and configuration
+- **QUICK_REFERENCE.md** - Common commands and usage patterns
+
+## 🔍 Available Examples
+
+### ⏰ [Issue Expiration with Visible Checkbox](./expiration-visible-checkbox/)
+Automatically create issues with visible, user-controllable expiration dates using checkbox formatting.
+
+**Use Cases**: Time-limited announcements, demo issues, periodic reminders, ephemeral content
+
+### 🏷️ [Slash Command with Labels](./slash-command-with-labels/)
+Demonstrates combining slash command triggers with label-based automation for flexible workflow activation.
+
+**Use Cases**: Manual triage, auto-routing, hybrid workflows, label-based actions
+
+### 🧪 [Test Setup CLI Action](./test-setup-cli/)
+Demonstrates installing and verifying the gh-aw CLI in GitHub Actions workflows.
+
+**Use Cases**: CI/CD integration, version testing, automated deployment, workflow testing
+
+## 📝 Creating Your Own Workflow Documentation
+
+See [DOCUMENTATION_TEMPLATE.md](./DOCUMENTATION_TEMPLATE.md) for a complete guide on creating standardized documentation for your workflows. The template includes:
+
+1. **README.md** (Required) - Overview and quick start
+2. **SETUP.md** (Required) - Installation instructions
+3. **QUICK_REFERENCE.md** (Required) - Command reference
+4. **CUSTOMIZATION.md** (Optional) - Framework adaptations
+5. **TESTING.md** (Optional) - Testing strategies
+
+## 🎯 Documentation Standards
+
+All workflow documentation follows these patterns from high-scoring workflows:
+
+- ✨ **Emojis** in headers for visual organization
+- 📝 **Code blocks** with syntax highlighting
+- 📊 **Tables** for structured reference data
+- ✅ **Checklists** for prerequisites and validation
+- 🔗 **Links** to related workflows and resources
+
+## 🚀 Quick Start
+
+To use any example workflow:
+
+1. Browse to the workflow directory
+2. Read the **README.md** for an overview
+3. Follow the **SETUP.md** for installation
+4. Reference **QUICK_REFERENCE.md** for common patterns
+
+## 💡 Contributing
+
+When adding new example workflows, please follow the structure documented in [DOCUMENTATION_TEMPLATE.md](./DOCUMENTATION_TEMPLATE.md) to maintain consistency across examples.

examples/workflows/expiration-visible-checkbox/QUICK_REFERENCE.md

@@ -0,0 +1,109 @@
+# ⚡ Quick Reference
+
+## Common Commands
+
+### Compile Workflow
+```bash
+gh aw compile .github/workflows/expiration-visible-checkbox.md
+```
+
+### Run Workflow Manually
+```bash
+gh workflow run expiration-visible-checkbox.lock.yml
+```
+
+### View Recent Runs
+```bash
+gh run list --workflow=expiration-visible-checkbox.lock.yml
+```
+
+### Check Created Issues
+```bash
+gh issue list --label ephemeral
+```
+
+## Usage Patterns
+
+### Pattern 1: Manual Trigger (Default)
+```yaml
+---
+engine: copilot
+on: manual
+safe-outputs:
+  create-issue:
+    expires: 7
+---
+```
+
+### Pattern 2: Daily Creation
+```yaml
+---
+engine: copilot
+on: schedule: daily
+safe-outputs:
+  create-issue:
+    expires: 1  # Expires next day
+---
+```
+
+### Pattern 3: Custom Expiration
+```yaml
+---
+engine: copilot
+on: manual
+safe-outputs:
+  create-issue:
+    title: "Weekly Status Update"
+    expires: 7
+    labels: [status, weekly, ephemeral]
+---
+```
+
+## Configuration Options
+
+| Option | Values | Description |
+|--------|--------|-------------|
+| `engine` | `copilot`, `claude`, `codex` | AI engine to use |
+| `on` | `manual`, `schedule`, `issues` | Trigger type |
+| `expires` | `1-365` (days) | Days until automatic expiration |
+| `labels` | Array of strings | Labels to apply to issue |
+
+## Safe Outputs
+
+This workflow uses the `create-issue` safe output:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `title` | string | Title of the issue to create |
+| `expires` | integer | Number of days until expiration |
+| `labels` | array | Labels to apply to the issue |
+
+## Expiration Checkbox Format
+
+Issues created with expiration will include:
+
+```markdown
+- [x] expires <!-- gh-aw-expires: 2026-01-25T12:00:00.000Z --> on Jan 25, 2026, 12:00 PM UTC
+```
+
+**Checkbox States**:
+- `[x]` (checked): Issue will be automatically closed at expiration
+- `[ ]` (unchecked): Issue will not be automatically closed
+
+## Workflow Prompts
+
+You can customize the issue body by modifying the prompt in the workflow file. The default prompt creates:
+- Issue overview explaining visible expiration
+- Comparison of old vs new format
+- Benefits list
+- How it works section
+
+## Tips
+
+💡 **Tip 1**: Use `ephemeral` label for easy filtering of temporary issues
+
+💡 **Tip 2**: Set shorter expiration times (1-3 days) for demo purposes
+
+💡 **Tip 3**: Uncheck the expiration box in created issues to prevent auto-closure
+
+💡 **Tip 4**: Combine with scheduled triggers for recurring temporary issues

examples/workflows/expiration-visible-checkbox/README.md

@@ -0,0 +1,63 @@
+# ⏰ Issue Expiration with Visible Checkbox
+
+Automatically create issues with visible, user-controllable expiration dates using checkbox formatting.
+
+## Overview
+
+This workflow demonstrates the new visible expiration format for GitHub Agentic Workflows. Instead of hiding expiration dates in XML comments, this approach uses a visible checkbox that users can see and interact with directly in the issue body.
+
+The visible checkbox format makes expiration dates transparent to users while still allowing automated cleanup. Users can uncheck the expiration box if they want to keep an issue open beyond the initial expiration date, giving them direct control over the lifecycle of automated issues.
+
+This pattern is particularly useful for creating temporary demonstration issues, time-limited announcements, or automated cleanup of ephemeral content.
+
+## Use Cases
+
+- 📢 **Time-Limited Announcements**: Create issues that automatically expire after a specific period
+- 🧪 **Demo Issues**: Generate example issues that self-clean to avoid clutter
+- 🔄 **Periodic Reminders**: Create recurring issues that auto-close after being addressed
+- 🗑️ **Ephemeral Content**: Manage short-lived issues that don't need permanent tracking
+
+## Key Features
+
+- ✅ **Visible Expiration**: Users can see exactly when an issue will expire
+- 🎛️ **User Control**: Checkbox can be unchecked to prevent automatic closure
+- 📅 **Human-Readable Dates**: Shows both ISO timestamp and friendly date format
+- 🤖 **Automated Cleanup**: Maintenance workflow automatically closes expired issues
+- 🏷️ **Label Support**: Automatically applies labels like "ephemeral" for easy filtering
+
+## Quick Start
+
+See [SETUP.md](./SETUP.md) for detailed installation and configuration steps, or jump to [QUICK_REFERENCE.md](./QUICK_REFERENCE.md) for common usage patterns.
+
+## Example Output
+
+When this workflow runs, it creates an issue with a body that includes:
+
+```markdown
+## Example Issue
+
+This issue demonstrates the new visible expiration format for GitHub Agentic Workflows.
+
+### What Changed
+
+Previously, expiration was hidden in an XML comment:
+```html
+<!-- gh-aw-expires: 2026-01-25T12:00:00.000Z -->
+```
+
+Now, expiration is visible as a checkbox that users can interact with:
+```markdown
+- [x] expires <!-- gh-aw-expires: 2026-01-25T12:00:00.000Z --> on Jan 25, 2026, 12:00 PM UTC
+```
+
+### Benefits
+
+1. **Visible**: Users can see when the issue will expire
+2. **Configurable**: Users can uncheck the box to prevent expiration
+3. **Informative**: Shows both ISO date and human-readable format
+```
+
+## Related Workflows
+
+- [Slash Command with Labels](../slash-command-with-labels/) - Demonstrates label-based workflow triggering
+- [Test Setup CLI](../test-setup-cli/) - Example of testing CLI installation in workflows

examples/workflows/expiration-visible-checkbox/SETUP.md

@@ -0,0 +1,126 @@
+# 🛠️ Setup Guide
+
+## Prerequisites
+
+Before setting up this workflow, ensure you have:
+
+- [ ] Repository write access
+- [ ] GitHub Actions enabled
+- [ ] `gh-aw` CLI installed (`gh extension install githubnext/gh-aw`)
+- [ ] Required permissions: `issues: write`, `contents: read`
+
+## Installation Steps
+
+### 1. Add the Workflow File
+
+Copy the workflow file to your repository:
+
+```bash
+mkdir -p .github/workflows
+cp examples/workflows/expiration-visible-checkbox/workflow.md .github/workflows/expiration-visible-checkbox.md
+```
+
+### 2. Compile the Workflow
+
+```bash
+gh aw compile .github/workflows/expiration-visible-checkbox.md
+```
+
+This generates the `.lock.yml` file that GitHub Actions will execute.
+
+### 3. Review Configuration
+
+The workflow uses these default settings:
+
+```yaml
+---
+engine: copilot
+on: manual
+safe-outputs:
+  create-issue:
+    title: "Example Issue with Visible Expiration"
+    expires: 7  # Expires in 7 days
+    labels: [example, ephemeral]
+---
+```
+
+You can customize:
+- `expires`: Number of days until expiration (default: 7)
+- `labels`: Labels to apply to the created issue
+- `title`: Title of the created issue
+
+### 4. Enable the Workflow
+
+Commit and push the compiled workflow:
+
+```bash
+git add .github/workflows/expiration-visible-checkbox.*
+git commit -m "Add expiration-visible-checkbox workflow"
+git push
+```
+
+## Configuration
+
+### Trigger Options
+
+By default, the workflow uses `on: manual`, meaning it only runs when manually triggered. You can change this:
+
+**Run on a schedule:**
+```yaml
+on: schedule: daily
+```
+
+**Run on issue events:**
+```yaml
+on:
+  issues:
+    types: [opened, labeled]
+```
+
+### Expiration Duration
+
+Adjust the expiration time by changing the `expires` value:
+
+```yaml
+safe-outputs:
+  create-issue:
+    expires: 3   # 3 days
+    # or
+    expires: 14  # 2 weeks
+```
+
+### Issue Labels
+
+Customize the labels applied to created issues:
+
+```yaml
+safe-outputs:
+  create-issue:
+    labels: [example, ephemeral, temporary]
+```
+
+## Verification
+
+To verify the workflow is working:
+
+1. Navigate to **Actions** tab in your repository
+2. Find "expiration-visible-checkbox" workflow
+3. Click **Run workflow** to trigger it manually
+4. Check the **Issues** tab for the newly created issue
+5. Verify the issue contains a visible expiration checkbox
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue**: Workflow doesn't appear in Actions tab
+- **Solution**: Ensure both `.md` and `.lock.yml` files were committed
+
+**Issue**: Permission denied when creating issue
+- **Solution**: Verify workflow has `issues: write` permission in frontmatter
+
+**Issue**: Issue created but no expiration checkbox
+- **Solution**: Check that `expires` parameter is set in `safe-outputs.create-issue`
+
+**Issue**: Expiration checkbox shows incorrect date
+- **Solution**: Verify system time is correct, expiration is calculated from current time + days