Feature/add documentation and copilot instructions

.gitattributes

@@ -0,0 +1 @@
+.github/workflows/*.lock.yml linguist-generated=true merge=ours

.github/CODEOWNERS

@@ -0,0 +1,14 @@
+# CODEOWNERS — uncomment and customize after creating a repo from this template.
+# See: https://docs.github.com/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+#
+# Default owners for everything in the repo
+# * @your-org/your-team
+#
+# Agent-specific ownership
+# agents/agent1/ @your-org/agent1-team
+#
+# CI / workflow changes require admin review
+# .github/ @your-org/platform-team
+#
+# Documentation
+# docs/ @your-org/docs-team

.github/actions/setup-python-env/README.md

@@ -0,0 +1,62 @@
+# Setup Python Environment
+
+Composite GitHub Action that sets up [uv](https://docs.astral.sh/uv/) with a
+specific Python version and installs project dependencies via `uv sync`.
+
+## Inputs
+
+| Input | Required | Default | Description |
+|---|---|---|---|
+| `python-version` | No | `"3.13"` | Python version to install (e.g. `"3.13"`, `"3.10"`). |
+| `include-docs` | No | `"false"` | When `"true"`, adds `--group docs` to install Sphinx and related packages. |
+| `extra-args` | No | `""` | Additional arguments appended to the `uv sync` command. Must be a trusted, static flag string — see [Security note](#security-note) below. |
+
+The base command is always `uv sync --all-extras --dev`. The `include-docs` flag
+and `extra-args` extend it.
+
+## Security note
+
+`extra-args` is passed to `uv sync` via an environment variable and intentionally
+word-split so that callers can supply multiple flags (e.g.
+`--all-packages --prerelease=if-necessary-or-explicit`). A defensive guard
+validates each token before execution: every token must start with `-` and
+contain only alphanumeric characters and safe flag characters (`=`, `.`, `:`,
+`/`, `@`, `+`, `-`). Tokens that do not match this pattern cause the action to
+fail immediately with an error. Despite this guard, **only hardcoded, static
+strings should be used**. Never pass dynamic values sourced from issue bodies,
+PR descriptions, user-controlled inputs, or any other external source, as those
+could introduce unexpected `uv sync` flags and alter environment resolution
+behaviour.
+
+## Usage
+
+### Minimal (defaults to Python 3.13)
+
+```yaml
+- uses: ./.github/actions/setup-python-env
+```
+
+### With a Python version matrix
+
+```yaml
+- uses: ./.github/actions/setup-python-env
+  with:
+    python-version: ${{ matrix.python-version }}
+```
+
+### Including docs dependencies
+
+```yaml
+- uses: ./.github/actions/setup-python-env
+  with:
+    include-docs: "true"
+```
+
+### With extra sync arguments
+
+```yaml
+- uses: ./.github/actions/setup-python-env
+  with:
+    include-docs: "true"
+    extra-args: "--all-packages -U --prerelease=if-necessary-or-explicit"
+```

.github/actions/setup-python-env/action.yml

@@ -0,0 +1,53 @@
+name: "Setup Python environment"
+description: "Set up uv with Python and install project dependencies."
+
+inputs:
+  python-version:
+    description: "Python version to install (e.g. '3.13', '3.10')."
+    required: false
+    default: "3.13"
+  include-docs:
+    description: "Install the docs dependency group (sphinx, sphinx_autodoc_typehints, …)."
+    required: false
+    default: "false"
+  extra-args:
+    description: "Additional arguments appended to the `uv sync` command."
+    required: false
+    default: ""
+
+runs:
+  using: composite
+  steps:
+    - name: Set up uv
+      uses: astral-sh/setup-uv@f0ec1fc3b38f5e7cd731bb6ce540c5af426746bb # v5.4.2
+      with:
+        python-version: ${{ inputs.python-version }}
+        enable-cache: true
+
+    - name: Install dependencies
+      shell: bash
+      env:
+        EXTRA_ARGS: ${{ inputs.extra-args }}
+        INCLUDE_DOCS: ${{ inputs.include-docs }}
+      run: |
+        args="--all-extras --dev"
+        if [[ "$INCLUDE_DOCS" == "true" ]]; then
+          args="$args --group docs"
+        fi
+        if [[ -n "$EXTRA_ARGS" ]]; then
+          # Validate each whitespace-split token: must start with '-' and contain only safe flag characters.
+          # NOTE: '--' (end-of-options marker) is intentionally allowed; positional args would fail validation.
+          for arg in $EXTRA_ARGS; do
+            # Denylist: block flags that could redirect dependency resolution to an attacker-controlled index.
+            if [[ "$arg" =~ ^--(index-url|extra-index-url|trusted-host|find-links)(=|$) ]]; then
+              echo "::error::Blocked dangerous extra-args token: '$arg'. Registry overrides are not permitted." >&2
+              exit 1
+            fi
+            if [[ ! "$arg" =~ ^-[a-zA-Z0-9=._:/@+-]+$ ]]; then
+              echo "::error::Unsafe extra-args token: '$arg'. Each token must start with '-' and contain only safe flag characters." >&2
+              exit 1
+            fi
+          done
+        fi
+        # shellcheck disable=SC2086  # intentional word-splitting for uv flags (all tokens validated above)
+        uv sync $args $EXTRA_ARGS

.github/agents/agentic-workflows.agent.md

@@ -0,0 +1,143 @@
+---
+description: GitHub Agentic Workflows (gh-aw) - Create, debug, and upgrade AI-powered workflows with intelligent prompt routing
+disable-model-invocation: true
+---
+
+# GitHub Agentic Workflows Agent
+
+This agent helps you work with **GitHub Agentic Workflows (gh-aw)**, a CLI extension for creating AI-powered workflows in natural language using markdown files.
+
+## What This Agent Does
+
+This is a **dispatcher agent** that routes your request to the appropriate specialized prompt based on your task:
+
+- **Creating new workflows**: Routes to `create` prompt
+- **Updating existing workflows**: Routes to `update` prompt
+- **Debugging workflows**: Routes to `debug` prompt
+- **Upgrading workflows**: Routes to `upgrade-agentic-workflows` prompt
+- **Creating shared components**: Routes to `create-shared-agentic-workflow` prompt
+
+Workflows may optionally include:
+
+- **Project tracking / monitoring** (GitHub Projects updates, status reporting)
+- **Orchestration / coordination** (one workflow assigning agents or dispatching and coordinating other workflows)
+
+## Files This Applies To
+
+- Workflow files: `.github/workflows/*.md` and `.github/workflows/**/*.md`
+- Workflow lock files: `.github/workflows/*.lock.yml`
+- Shared components: `.github/workflows/shared/*.md`
+- Configuration: https://github.com/github/gh-aw/blob/v0.46.0/.github/aw/github-agentic-workflows.md
+
+## Problems This Solves
+
+- **Workflow Creation**: Design secure, validated agentic workflows with proper triggers, tools, and permissions
+- **Workflow Debugging**: Analyze logs, identify missing tools, investigate failures, and fix configuration issues
+- **Version Upgrades**: Migrate workflows to new gh-aw versions, apply codemods, fix breaking changes
+- **Component Design**: Create reusable shared workflow components that wrap MCP servers
+
+## How to Use
+
+When you interact with this agent, it will:
+
+1. **Understand your intent** - Determine what kind of task you're trying to accomplish
+2. **Route to the right prompt** - Load the specialized prompt file for your task
+3. **Execute the task** - Follow the detailed instructions in the loaded prompt
+
+## Available Prompts
+
+### Create New Workflow
+**Load when**: User wants to create a new workflow from scratch, add automation, or design a workflow that doesn't exist yet
+
+**Prompt file**: https://github.com/github/gh-aw/blob/v0.46.0/.github/aw/create-agentic-workflow.md
+
+**Use cases**:
+- "Create a workflow that triages issues"
+- "I need a workflow to label pull requests"
+- "Design a weekly research automation"
+
+### Update Existing Workflow
+**Load when**: User wants to modify, improve, or refactor an existing workflow
+
+**Prompt file**: https://github.com/github/gh-aw/blob/v0.46.0/.github/aw/update-agentic-workflow.md
+
+**Use cases**:
+- "Add web-fetch tool to the issue-classifier workflow"
+- "Update the PR reviewer to use discussions instead of issues"
+- "Improve the prompt for the weekly-research workflow"
+
+### Debug Workflow
+**Load when**: User needs to investigate, audit, debug, or understand a workflow, troubleshoot issues, analyze logs, or fix errors
+
+**Prompt file**: https://github.com/github/gh-aw/blob/v0.46.0/.github/aw/debug-agentic-workflow.md
+
+**Use cases**:
+- "Why is this workflow failing?"
+- "Analyze the logs for workflow X"
+- "Investigate missing tool calls in run #12345"
+
+### Upgrade Agentic Workflows
+**Load when**: User wants to upgrade workflows to a new gh-aw version or fix deprecations
+
+**Prompt file**: https://github.com/github/gh-aw/blob/v0.46.0/.github/aw/upgrade-agentic-workflows.md
+
+**Use cases**:
+- "Upgrade all workflows to the latest version"
+- "Fix deprecated fields in workflows"
+- "Apply breaking changes from the new release"
+
+### Create Shared Agentic Workflow
+**Load when**: User wants to create a reusable workflow component or wrap an MCP server
+
+**Prompt file**: https://github.com/github/gh-aw/blob/v0.46.0/.github/aw/create-shared-agentic-workflow.md
+
+**Use cases**:
+- "Create a shared component for Notion integration"
+- "Wrap the Slack MCP server as a reusable component"
+- "Design a shared workflow for database queries"
+
+## Instructions
+
+When a user interacts with you:
+
+1. **Identify the task type** from the user's request
+2. **Load the appropriate prompt** from the GitHub repository URLs listed above
+3. **Follow the loaded prompt's instructions** exactly
+4. **If uncertain**, ask clarifying questions to determine the right prompt
+
+## Quick Reference
+
+```bash
+# Initialize repository for agentic workflows
+gh aw init
+
+# Generate the lock file for a workflow
+gh aw compile [workflow-name]
+
+# Debug workflow runs
+gh aw logs [workflow-name]
+gh aw audit <run-id>
+
+# Upgrade workflows
+gh aw fix --write
+gh aw compile --validate
+```
+
+## Key Features of gh-aw
+
+- **Natural Language Workflows**: Write workflows in markdown with YAML frontmatter
+- **AI Engine Support**: Copilot, Claude, Codex, or custom engines
+- **MCP Server Integration**: Connect to Model Context Protocol servers for tools
+- **Safe Outputs**: Structured communication between AI and GitHub API
+- **Strict Mode**: Security-first validation and sandboxing
+- **Shared Components**: Reusable workflow building blocks
+- **Repo Memory**: Persistent git-backed storage for agents
+- **Sandboxed Execution**: All workflows run in the Agent Workflow Firewall (AWF) sandbox, enabling full `bash` and `edit` tools by default
+
+## Important Notes
+
+- Always reference the instructions file at https://github.com/github/gh-aw/blob/v0.46.0/.github/aw/github-agentic-workflows.md for complete documentation
+- Use the MCP tool `agentic-workflows` when running in GitHub Copilot Cloud
+- Workflows must be compiled to `.lock.yml` files before running in GitHub Actions
+- **Bash tools are enabled by default** - Don't restrict bash commands unnecessarily since workflows are sandboxed by the AWF
+- Follow security best practices: minimal permissions, explicit network access, no template injection