diff --git a/.github/agents/agentic-workflows.agent.md b/.github/agents/agentic-workflows.agent.md index 72dae5f2e5..f71fc03a66 100644 --- a/.github/agents/agentic-workflows.agent.md +++ b/.github/agents/agentic-workflows.agent.md @@ -96,6 +96,30 @@ When you interact with this agent, it will: - "Wrap the Slack MCP server as a reusable component" - "Design a shared workflow for database queries" +### Orchestration and Delegation + +**Load when**: Creating or updating workflows that coordinate multiple agents or dispatch work to other workflows + +**Prompt file**: https://github.com/github/gh-aw/blob/main/.github/aw/orchestration.md + +**Use cases**: +- Assigning work to AI coding agents +- Dispatching specialized worker workflows +- Using correlation IDs for tracking +- Orchestration design patterns + +### GitHub Projects Integration + +**Load when**: Creating or updating workflows that manage GitHub Projects v2 + +**Prompt file**: https://github.com/github/gh-aw/blob/main/.github/aw/projects.md + +**Use cases**: +- Tracking items and fields with update-project +- Posting periodic run summaries +- Creating new projects +- Projects v2 authentication and configuration + ## Instructions When a user interacts with you: @@ -111,9 +135,6 @@ When a user interacts with you: # Initialize repository for agentic workflows gh aw init -# Create a new workflow -gh aw new - # Compile workflows gh aw compile [workflow-name] diff --git a/.github/aw/orchestration.md b/.github/aw/orchestration.md new file mode 100644 index 0000000000..b708692ae5 --- /dev/null +++ b/.github/aw/orchestration.md @@ -0,0 +1,153 @@ +--- +description: Orchestration and delegation patterns for agentic workflows +--- + +# Orchestration / Delegation Patterns + +When designing workflows that coordinate multiple agents or other workflows, use these orchestration patterns. + +## When to Use Orchestration + +Use orchestration patterns when designing workflows that: + +- Coordinate multiple agents working on related tasks +- Dispatch work to specialized worker workflows +- Break down complex tasks into manageable units +- Need to track and correlate related work items + +## Core Delegation Patterns + +### 1. Assign to AI Coding Agent + +Use `assign-to-agent` when you have an issue or PR that describes a concrete unit of work and want to delegate it to an AI coding agent. + +**Best for**: Code changes, bug fixes, feature implementation, refactoring + +### 2. Dispatch Specialized Worker Workflow + +Use `dispatch-workflow` when you want a repeatable, scoped worker with its own dedicated prompt, tools, and permissions. + +**Best for**: Repeated analysis tasks, scheduled reports, multi-step workflows with specific requirements + +### 3. Combined Approach + +You can combine these patterns: dispatch a worker workflow that then assigns work to agents based on analysis results. + +## Configuration Best Practices + +### Correlation IDs (Strongly Recommended) + +Always include at least one stable correlation identifier in delegated work to track related tasks and workflow executions: + +- **`tracker_issue_number`**: Link work items to a tracking issue +- **`bundle_key`**: Group related items (e.g., `"npm :: package-lock.json"`) +- **`run_id`**: Use `${{ github.run_id }}` or a custom identifier (e.g., `"run-2026-02-04-001"`) + +Correlation IDs enable: +- Progress tracking across multiple workflow runs +- Debugging and troubleshooting complex orchestrations +- Analytics and reporting on workflow performance +- Avoiding duplicate work + +## Assign-to-Agent Configuration + +**Frontmatter setup:** + +```yaml wrap +safe-outputs: + assign-to-agent: + name: "copilot" # default agent (optional) + allowed: [copilot] # optional allowlist + target: "*" # "triggering" (default), "*", or number + max: 10 +``` + +**Agent output format:** + +```text +assign_to_agent(issue_number=123, agent="copilot") + +# Works with temporary IDs too (same run) +assign_to_agent(issue_number="aw_abc123def456", agent="copilot") +``` + +**Notes:** +- Requires `GH_AW_AGENT_TOKEN` environment variable for automated agent assignment +- Temporary IDs (`aw_...`) are supported for `issue_number` (within the same workflow run) +- Use `target: "*"` to assign any issue, or `"triggering"` (default) to only assign the triggering issue + +## Dispatch-Workflow Configuration + +**Frontmatter setup:** + +```yaml wrap +safe-outputs: + dispatch-workflow: + workflows: [worker-a, worker-b] + max: 10 +``` + +**Notes:** +- Each worker workflow must exist in `.github/workflows/` and support `workflow_dispatch` trigger +- Define explicit `workflow_dispatch.inputs` on worker workflows so dispatch tools get the correct schema +- Worker workflows receive inputs as strings (convert booleans/numbers as needed) + +**Example: Calling dispatched workflows** + +Preferred approach - use the generated tool for the worker (hyphens become underscores): + +```javascript +// If your workflow allowlists "worker-a", the tool name is "worker_a" +worker_a({ + tracker_issue: 123, + work_item_id: "item-001", + dry_run: false +}) +``` + +Alternative: Equivalent JSON format for agent output: + +```json +{ + "type": "dispatch_workflow", + "workflow_name": "worker-a", + "inputs": { + "tracker_issue": "123", + "work_item_id": "item-001", + "dry_run": "false" + } +} +``` + +## Design Guidelines for Orchestrator Workflows + +When creating orchestrator workflows, follow these best practices: + +1. **Clear Separation of Concerns**: Orchestrators should coordinate, not do heavy processing themselves +2. **Explicit Dependencies**: Document which workers/agents are expected to be available +3. **Error Handling**: Plan for worker failures and implement retry or fallback strategies +4. **Progress Tracking**: Use correlation IDs and status updates to track orchestration progress +5. **Idempotency**: Design workflows to be safely re-runnable without causing duplicate work +6. **Observability**: Log orchestration decisions and delegation events for debugging + +## Common Orchestration Patterns + +### Pattern: Issue Triage and Assignment +1. Orchestrator analyzes incoming issues +2. Classifies and labels them +3. Assigns to appropriate agent based on issue type + +### Pattern: Bulk Processing with Workers +1. Orchestrator queries for work items +2. Dispatches specialized workers for each item +3. Collects results and generates summary report + +### Pattern: Sequential Delegation +1. First agent performs analysis and creates issue +2. Orchestrator assigns issue to second agent for implementation +3. Third agent reviews and merges changes + +## References + +- For full configuration options, see: [github-agentic-workflows.md](https://github.com/github/gh-aw/blob/main/.github/aw/github-agentic-workflows.md) +- For safe-outputs documentation, see the `safe-outputs:` section in the main configuration guide diff --git a/.github/aw/projects.md b/.github/aw/projects.md new file mode 100644 index 0000000000..869dde1200 --- /dev/null +++ b/.github/aw/projects.md @@ -0,0 +1,145 @@ +--- +description: GitHub Projects (v2) integration patterns for agentic workflows +--- + +# GitHub Projects (v2) Integration + +When designing workflows that manage GitHub Projects, use these patterns and best practices. + +## When to Use Projects Integration + +Use GitHub Projects safe-outputs when designing workflows that: + +- Track issues and pull requests across multiple repositories +- Maintain project boards with automated status updates +- Generate periodic project status summaries +- Coordinate work across teams with consistent field updates + +## Core Projects Patterns + +- **Track items and fields** with `update-project` (add issue/PR items, create/update fields, optionally create views) +- **Post periodic run summaries** with `create-project-status-update` (status, dates, and a concise markdown summary) +- **Create new projects** with `create-project` (optional; prefer manual creation unless automation is explicitly desired) + +## Prerequisites and Authentication + +**Important**: Projects v2 requires a **PAT** or **GitHub App token** with Projects permissions. The default `GITHUB_TOKEN` cannot manage Projects v2. + +- Always store the token in a repo/org secret (recommended: `GH_AW_PROJECT_GITHUB_TOKEN`) and reference it in safe-output config +- Always use the **full project URL** (example: `https://github.com/orgs/myorg/projects/42`) +- The agent must include `project` in **every** `update_project` / `create_project_status_update` output +- The configured `project` value is for documentation and validation only + +## Workflow Configuration + +**Frontmatter setup:** + +```yaml +safe-outputs: + update-project: + project: "https://github.com/orgs//projects/" # required (replace) + max: 20 + github-token: ${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }} + + create-project-status-update: + project: "https://github.com/orgs//projects/" # required (replace) + max: 1 + github-token: ${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }} + + # Optional: only enable if the workflow is allowed to create new projects + # create-project: + # max: 1 + # github-token: ${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }} + # target-owner: "myorg" # optional default owner + # title-prefix: "Project" # optional +``` + +**Notes:** +- Keep `max` small. For `create-project-status-update`, `max: 1` is almost always enough +- If you want the agent to read project metadata (fields/items) during reasoning, also configure `tools.github.toolsets: [projects]` with a token that has Projects access + +## Agent Output Patterns + +### 1. Add an issue/PR to a project and set fields + +```javascript +update_project({ + project: "https://github.com/orgs/myorg/projects/42", + content_type: "issue", + content_number: 123, + fields: { + Status: "Todo", + Priority: "High" + } +}) +``` + +### 2. Create a draft issue in the project + +```javascript +update_project({ + project: "https://github.com/orgs/myorg/projects/42", + content_type: "draft_issue", + draft_title: "Triage: follow-up investigation", + draft_body: "Short context and next steps.", + fields: { + Status: "Backlog" + } +}) +``` + +### 3. Post a project status update (run summary) + +```javascript +create_project_status_update({ + project: "https://github.com/orgs/myorg/projects/42", + status: "ON_TRACK", + start_date: "2026-02-04", + target_date: "2026-02-18", + body: "## Run summary\n\n- Processed 12 items\n- Added 3 new issues to the board\n- Next: tackle 2 blocked tasks" +}) +``` + +### 4. Create a new project (optional) + +Prefer creating projects manually unless the workflow is explicitly intended to bootstrap new projects. + +```javascript +create_project({ + title: "Project: Q1 reliability", + owner: "myorg", + owner_type: "org", + item_url: "https://github.com/myorg/repo/issues/123" +}) +``` + +## Design Guidelines + +### Guardrails and Conventions + +- **Single source of truth**: Store a concept (e.g., Target ship date) in exactly one place (a single field), not spread across multiple similar fields +- **Prefer small, stable field vocabularies**: Standardize field names like `Status`, `Priority`, `Sprint`, `Target date`. Avoid creating near-duplicates +- **Don't create projects implicitly**: For `update_project`, only set `create_if_missing: true` when the workflow is explicitly allowed to create/own project boards +- **Keep status updates tight**: 5-20 lines is usually plenty; use headings + short bullets +- **Use issues/PRs for detailed discussion**: Put deep context on the issue/PR; keep the project item fields for tracking/triage + +### Project Management Best Practices + +When designing how your workflow should manage a project board: + +- **Communicate via issues and PRs**: Use assignees, @mentions, links between work items, and clear ownership. Let the project reflect the state, not replace conversation +- **Break down large work**: Prefer smaller issues and PRs; use sub-issues and dependencies so blockers are explicit; use milestones/labels to connect work to larger goals +- **Document the project**: Use the project description/README to explain purpose, how to use views, and who to contact. Use status updates for high-level progress +- **Use the right views**: Maintain a few views for the most common workflows (table for detail, board for flow, roadmap for timeline) and keep filters/grouping meaningful +- **Use field types intentionally**: Choose fields that power decisions (iteration, single-select status/priority, dates). Avoid redundant or low-signal metadata +- **Automate the boring parts**: Rely on built-in project workflows where possible; use GitHub Actions + GraphQL (via these safe outputs) for consistent updates +- **Visualize progress**: Consider charts/insights for trends (throughput, blocked items, work by status/iteration) and share them with stakeholders +- **Standardize with templates**: If multiple teams/projects follow the same process, prefer templates with prebuilt views/fields +- **Link to teams and repos**: Connect projects to the team and/or repo for discoverability and consistent access +- **Have a single source of truth**: Track important metadata (dates, status) in one place so updates don't drift + +## References + +- For full configuration options, see: [github-agentic-workflows.md](https://github.com/github/gh-aw/blob/main/.github/aw/github-agentic-workflows.md) +- For safe-outputs documentation, see the `safe-outputs:` section in the main configuration guide +- GitHub Projects best practices: https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/best-practices-for-projects diff --git a/.github/workflows/shared/orchestration.md b/.github/workflows/shared/orchestration.md deleted file mode 100644 index 4278bafd00..0000000000 --- a/.github/workflows/shared/orchestration.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -# Shared: Orchestration / Delegation patterns -# -# Import this file when your workflow delegates work to: -# - a coding agent (`assign-to-agent`), and/or -# - a specialized worker workflow (`dispatch-workflow`). ---- - -## Orchestration / Delegation - -Use these patterns when an orchestrator workflow needs to delegate work: - -- **Assign to an AI coding agent** (`assign-to-agent`) when you already have an issue/PR that describes a concrete unit of work. -- **Dispatch a specialized worker workflow** (`dispatch-workflow`) when you want a repeatable, scoped worker with its own prompt/tools/permissions. - -You can combine them (dispatch a worker that then assigns an agent). - -### Correlation IDs (recommended) - -Always include at least one stable correlation identifier in delegated work: - -- `tracker_issue_number` -- `bundle_key` (for example `npm :: package-lock.json`) -- `run_id` (`${{ github.run_id }}`) or a custom string `run-YYYY-MM-DD-###` - -### Assign-to-agent - -Frontmatter: - -```yaml wrap -safe-outputs: - assign-to-agent: - name: "copilot" # default agent (optional) - allowed: [copilot] # optional allowlist - target: "*" # "triggering" (default), "*", or number - max: 10 -``` - -Agent output: - -```text -assign_to_agent(issue_number=123, agent="copilot") - -# Works with temporary IDs too (same run) -assign_to_agent(issue_number="aw_abc123def456", agent="copilot") -``` - -Notes: -- Requires `GH_AW_AGENT_TOKEN` for automated assignment. -- Temporary IDs (`aw_...`) are supported for `issue_number`. - -### Dispatch-workflow - -Frontmatter: - -```yaml wrap -safe-outputs: - dispatch-workflow: - workflows: [worker-a, worker-b] - max: 10 -``` - -Notes: -- Each worker must exist and support `workflow_dispatch`. -- Define explicit `workflow_dispatch.inputs` on workers so dispatch tools get the correct schema. - -Example calls (preferred): call the generated tool for the worker. - -If your workflow allowlists `worker-a`, the generated tool name will be `worker_a` (hyphens become underscores): - -```javascript -worker_a({ - tracker_issue: 123, - work_item_id: "item-001", - dry_run: false -}) -``` - -Equivalent agent output format: - -```json -{ - "type": "dispatch_workflow", - "workflow_name": "worker-a", - "inputs": { - "tracker_issue": "123", - "work_item_id": "item-001", - "dry_run": "false" - } -} -``` diff --git a/.github/workflows/shared/projects.md b/.github/workflows/shared/projects.md deleted file mode 100644 index 244a4d5602..0000000000 --- a/.github/workflows/shared/projects.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -# Shared: GitHub Projects (v2) -# -# Import this file in workflows that manage GitHub Projects via safe-outputs. -# This file is intentionally instruction-only (no config is applied automatically). -# -# Related safe-outputs: -# - update-project (agent output: update_project) -# - create-project-status-update (agent output: create_project_status_update) -# - create-project (agent output: create_project) ---- - -## GitHub Projects (v2): safe-output patterns - -Use these patterns when a workflow should keep a GitHub Project up-to-date: - -- **Track items and fields** with `update-project` (add issue/PR items, create/update fields, optionally create views). -- **Post periodic run summaries** with `create-project-status-update` (status, dates, and a concise markdown summary). -- **Create new projects** with `create-project` (optional; prefer manual creation unless automation is explicitly desired). - -### Import this shared file - -Add this to the importing workflow’s frontmatter: - -```yaml wrap -imports: - - shared/projects.md -``` - -### Prerequisites (read this first) - -- Projects v2 requires a **PAT** or **GitHub App token** with Projects permissions. The default `GITHUB_TOKEN` cannot manage Projects v2. -- Always store the token in a repo/org secret (recommended: `GH_AW_PROJECT_GITHUB_TOKEN`) and reference it in safe-output config. -- Always use the **full project URL** (example: `https://github.com/orgs/myorg/projects/42`). -- The agent must include `project` in **every** `update_project` / `create_project_status_update` output. The configured `project` value is for documentation and validation only. - -### Recommended workflow frontmatter - -Configure the safe outputs you intend to use in your workflow frontmatter: - -```yaml wrap -safe-outputs: - update-project: - project: "https://github.com/orgs//projects/" # required (replace) - max: 20 - github-token: ${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }} - - create-project-status-update: - project: "https://github.com/orgs//projects/" # required (replace) - max: 1 - github-token: ${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }} - - # Optional: only enable if the workflow is allowed to create new projects - # create-project: - # max: 1 - # github-token: ${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }} - # target-owner: "myorg" # optional default owner - # title-prefix: "Project" # optional -``` - -Notes: -- Keep `max` small. For `create-project-status-update`, `max: 1` is almost always enough. -- If you want the agent to read project metadata (fields/items) during reasoning, also configure `tools.github.toolsets: [projects]` with a token that has Projects access. - -### How to call the tools (agent output) - -#### 1) Add an issue/PR to a project and set fields - -```javascript -update_project({ - project: "https://github.com/orgs/myorg/projects/42", - content_type: "issue", - content_number: 123, - fields: { - Status: "Todo", - Priority: "High" - } -}) -``` - -#### 2) Create a draft issue in the project - -```javascript -update_project({ - project: "https://github.com/orgs/myorg/projects/42", - content_type: "draft_issue", - draft_title: "Triage: follow-up investigation", - draft_body: "Short context and next steps.", - fields: { - Status: "Backlog" - } -}) -``` - -#### 3) Post a project status update (run summary) - -```javascript -create_project_status_update({ - project: "https://github.com/orgs/myorg/projects/42", - status: "ON_TRACK", - start_date: "2026-02-04", - target_date: "2026-02-18", - body: "## Run summary\n\n- Processed 12 items\n- Added 3 new issues to the board\n- Next: tackle 2 blocked tasks" -}) -``` - -#### 4) Create a new project (optional) - -Prefer creating projects manually unless the workflow is explicitly intended to bootstrap new projects. - -```javascript -create_project({ - title: "Project: Q1 reliability", - owner: "myorg", - owner_type: "org", - item_url: "https://github.com/myorg/repo/issues/123" -}) -``` - -### Guardrails and conventions (recommended) - -- **Single source of truth**: store a concept (e.g., Target ship date) in exactly one place (a single field), not spread across multiple similar fields. -- **Prefer small, stable field vocabularies**: standardize field names like `Status`, `Priority`, `Sprint`, `Target date`. Avoid creating near-duplicates. -- **Don’t create projects implicitly**: for `update_project`, only set `create_if_missing: true` when the workflow is explicitly allowed to create/own project boards. -- **Keep status updates tight**: 5–20 lines is usually plenty; use headings + short bullets. -- **Use issues/PRs for detailed discussion**: put deep context on the issue/PR; keep the project item fields for tracking/triage. - -## Optional: Project management best practices (GitHub Docs) - -Use these as guidance when you’re designing how your workflow should manage a project board (not just how it calls tools). - -Source: https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/best-practices-for-projects - -- **Communicate via issues and PRs**: use assignees, @mentions, links between work items, and clear ownership. Let the project reflect the state, not replace conversation. -- **Break down large work**: prefer smaller issues and PRs; use sub-issues and dependencies so blockers are explicit; use milestones/labels to connect work to larger goals. -- **Document the project**: use the project description/README to explain purpose, how to use views, and who to contact. Use status updates for high-level progress. -- **Use the right views**: maintain a few views for the most common workflows (table for detail, board for flow, roadmap for timeline) and keep filters/grouping meaningful. -- **Use field types intentionally**: choose fields that power decisions (iteration, single-select status/priority, dates). Avoid redundant or low-signal metadata. -- **Automate the boring parts**: rely on built-in project workflows where possible; use GitHub Actions + GraphQL (via these safe outputs) for consistent updates. -- **Visualize progress**: consider charts/insights for trends (throughput, blocked items, work by status/iteration) and share them with stakeholders. -- **Standardize with templates**: if multiple teams/projects follow the same process, prefer templates with prebuilt views/fields. -- **Link to teams and repos**: connect projects to the team and/or repo for discoverability and consistent access. -- **Have a single source of truth**: track important metadata (dates, status) in one place so updates don’t drift.