diff --git a/.github/agents/agentic-workflows.agent.md b/.github/agents/agentic-workflows.agent.md index 6ae1702083..138ba4fbf2 100644 --- a/.github/agents/agentic-workflows.agent.md +++ b/.github/agents/agentic-workflows.agent.md @@ -96,30 +96,6 @@ 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: diff --git a/.github/aw/create-agentic-workflow.md b/.github/aw/create-agentic-workflow.md index d663bdc301..92dfafdaa0 100644 --- a/.github/aw/create-agentic-workflow.md +++ b/.github/aw/create-agentic-workflow.md @@ -226,8 +226,6 @@ These resources contain workflow patterns, best practices, safe outputs, and per - Media manipulation → `ffmpeg` (installed via `steps:`) - Code parsing/analysis → `ast-grep`, `codeql` (installed via `steps:`) - **Advanced static analysis** → See `.github/aw/serena-tool.md` for guidance on when and how to use Serena language server (only for advanced coding tasks when user explicitly requests it) - - **Orchestration patterns** → See `.github/aw/orchestration.md` for guidance on coordinating multi-step work and tracking progress across runs (use when the workflow is acting as a coordinator) - - **GitHub Projects (v2)** → See `.github/aw/projects.md` for GitHub Projects (v2) integration patterns and safe-outputs setup (use when the workflow updates project boards or posts project status updates) - **⚡ CLI Tool Discovery** → Before configuring complex manual setup, check if `gh aw` provides a CLI command for the task (see CLI Automation Discovery section below) - ⚠️ For GitHub write operations (creating issues, adding comments, etc.), always use `safe-outputs` instead of GitHub tools @@ -448,8 +446,6 @@ These resources contain workflow patterns, best practices, safe outputs, and per **Advanced static analysis tools**: For advanced code analysis tasks, see `.github/aw/serena-tool.md` for when and how to use Serena language server. - For coordinator-style workflows, see `.github/aw/orchestration.md` for orchestration patterns. - For goal-oriented workflows, see `.github/aw/monitoring.md` for goals, KPIs/metrics, and memory guidance. ⚠️ **IMPORTANT - Default Tools (Sandboxed by Default)**: - **Agentic workflows are sandboxed by the Agent Workflow Firewall (AWF)** - The agent runs in a secure, sandboxed environment with domain-based access control diff --git a/.github/aw/orchestration.md b/.github/aw/orchestration.md deleted file mode 100644 index b708692ae5..0000000000 --- a/.github/aw/orchestration.md +++ /dev/null @@ -1,153 +0,0 @@ ---- -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 deleted file mode 100644 index 3af9d9e535..0000000000 --- a/.github/aw/projects.md +++ /dev/null @@ -1,146 +0,0 @@ ---- -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 - -- **Create projects with automation** - Use `gh aw project new --with-project-setup` for quick setup with standard views and fields (recommended) -- **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 programmatically** with `create-project` safe-output (advanced; prefer CLI for initial setup) - -## 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