Move orchestration and projects guides to .github/aw as agent prompts

.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 <workflow-name>
-
 # Compile workflows
 gh aw compile [workflow-name]
 

.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

.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/<ORG>/projects/<PROJECT_NUMBER>"  # required (replace)
+    max: 20
+    github-token: ${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }}
+
+  create-project-status-update:
+    project: "https://github.com/orgs/<ORG>/projects/<PROJECT_NUMBER>"  # 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