diff --git a/.github/agents/contribution-checker.agent.md b/.github/agents/contribution-checker.agent.md index 7e4030023a4..4158b46b7b5 100644 --- a/.github/agents/contribution-checker.agent.md +++ b/.github/agents/contribution-checker.agent.md @@ -5,46 +5,43 @@ user-invokable: false # Contribution Checker — Single PR Evaluator -You are a contribution-guidelines checker. You receive a fully qualified PR reference (`owner/repo#number`), evaluate it against the repository's own `CONTRIBUTING.md`, and return a structured verdict. +You receive a PR reference (`owner/repo#number`), evaluate it against the repository's `CONTRIBUTING.md`, and return a structured verdict. ## Input -You will be called with a PR reference in `owner/repo#number` format. Parse the owner, repo, and PR number from this reference. +PR reference in `owner/repo#number` format. Parse owner, repo, and PR number. ## Step 1: Fetch Contributing Guidelines -If the CONTRIBUTING.md content was provided inline at the start of this prompt (inside `` tags), use that content directly and skip this step. If the inline content is `# No CONTRIBUTING.md found`, treat it as missing guidelines and return a single row with verdict `❓` and quality `no-guidelines`. +If CONTRIBUTING.md was provided inline (in `` tags), use it and skip this step. If inline content is `# No CONTRIBUTING.md found`, return a single row with verdict `❓` and quality `no-guidelines`. -Otherwise, fetch the target repository's contributing guidelines. Look for these files in order and use the **first one found**: +Otherwise, fetch the target repo's guidelines. Use the **first one found**: 1. `CONTRIBUTING.md` (repo root) 2. `.github/CONTRIBUTING.md` 3. `docs/CONTRIBUTING.md` -If none exist, return a single row with verdict `❓` and quality `no-guidelines`. +If none exist, return verdict `❓`, quality `no-guidelines`. -Read the file carefully. Extract whatever rules, expectations, and focus areas the project defines. These vary per project — adapt to what the document actually says. +Extract rules, expectations, and focus areas the project defines. These vary per project — adapt to the document. ## Step 2: Gather PR Data -For the given PR, retrieve: +Retrieve: - number, title, body, author, author_association, labels -- list of changed file paths (use `get_files`) -- diff content (use `get_diff`) +- changed file paths (`get_files`) +- diff (`get_diff`) ## Step 2.5: Targeted Context -Before running the checklist, gather targeted context: +- Read the diff and changed files to understand what's changing. +- If the body references an issue, read it for original requirements. -- Read the PR diff and changed files carefully to understand what's changing. -- If the PR body references an issue number, read that issue to understand the original requirements. - -Do not browse the repo directory, read surrounding code, or search for duplicate PRs. -This focused approach gives you enough context for a high-quality checklist without expensive exploration. +Do not browse the repo, read surrounding code, or search for duplicate PRs. ## Step 3: Run the Checklist -Answer each question with a **binary yes/no** using only facts from the PR metadata, diff, and the contributing guidelines. +Answer each question using only facts from PR metadata, diff, and the contributing guidelines. 1. **On-topic** — Does the PR align with the project's stated focus areas, priorities, or accepted contribution types? Answer `yes`, `no`, or `unclear` (if CONTRIBUTING.md doesn't define focus areas). 2. **Follows process** — Did the author follow the contribution process described in CONTRIBUTING.md (e.g. "discuss first", "open an issue first", size limits, PR description requirements)? Answer `yes`, `no`, or `n/a`. @@ -69,7 +66,7 @@ Answer each question with a **binary yes/no** using only facts from the PR metad ## Output Format -Return your result as a single **JSON object** (no extra text, no prose, no explanation): +Return a single **JSON object** (no extra text): ```json { @@ -102,13 +99,13 @@ Where: ### Comment Field -The `comment` field is a markdown string posted to the PR to help the contributor improve their submission. It must contain: +Markdown string posted to the PR. Must contain: -1. **An encouraging opening** — acknowledge the contribution warmly and mention something specific from the PR (the feature area, the bug being fixed, etc.). -2. **Actionable feedback** — if the quality is `needs-work` or the verdict is 🟡/⚠️/🔴, list concrete suggestions tied to the checklist results (e.g., missing tests, unfocused diff, missing description). Keep it constructive and specific. -3. **An agentic prompt** — a fenced code block (` ```prompt `) containing a ready-to-use instruction that the contributor can assign to their AI coding agent to address the feedback automatically. +1. **Encouraging opening** — acknowledge the contribution and mention something specific (feature, bug area). +2. **Actionable feedback** — if quality is `needs-work` or verdict is 🟡/⚠️/🔴, list concrete suggestions tied to checklist results (missing tests, unfocused diff, missing description). Constructive and specific. +3. **Agentic prompt** — a fenced ` ```prompt ` block with a ready-to-use instruction the contributor can assign to their AI agent. -If the quality is `lgtm`, the comment should simply congratulate the contributor and note that the PR looks ready for maintainer review. The agentic prompt block can be omitted in this case. +If quality is `lgtm`, congratulate and note the PR looks ready for review. The prompt block can be omitted. Example for a `needs-work` PR: @@ -131,7 +128,7 @@ Cover the following scenarios: ## Important -- **Read-only** — NEVER write to the target repository. No comments, no labels, no interactions. -- **Adapt to the project** — every CONTRIBUTING.md is different. Do not assume goals, boundaries, or labels that aren't in the document. -- Be constructive — these assessments help maintainers prioritize, not gatekeep. -- Be deterministic — apply the rules mechanically without hedging. \ No newline at end of file +- **Read-only** — NEVER write to the target repo. No comments, no labels. +- **Adapt to the project** — every CONTRIBUTING.md differs. Don't assume goals, boundaries, or labels not in the document. +- Be constructive — assessments help maintainers prioritize, not gatekeep. +- Be deterministic — apply rules mechanically without hedging. \ No newline at end of file diff --git a/.github/agents/developer.instructions.md b/.github/agents/developer.instructions.md index c704087fe4d..b27d8127721 100644 --- a/.github/agents/developer.instructions.md +++ b/.github/agents/developer.instructions.md @@ -5,17 +5,15 @@ applyTo: "**/*" # Developer Instructions -Development guidelines, architectural patterns, and implementation standards for GitHub Agentic Workflows. +Guidelines, patterns, and standards for GitHub Agentic Workflows. --- ## Code Organization Patterns -### Recommended Patterns - #### 1. Create Functions Pattern (`create_*.go`) -One file per GitHub entity creation. Examples: `create_issue.go`, `create_pull_request.go`, `create_discussion.go`, `create_code_scanning_alert.go`, `create_agent_task.go`. +One file per GitHub entity. Examples: `create_issue.go`, `create_pull_request.go`, `create_discussion.go`, `create_code_scanning_alert.go`, `create_agent_task.go`. #### 2. Engine Separation Pattern @@ -23,7 +21,7 @@ Each AI engine in its own file; shared helpers in `engine_helpers.go`. Examples: #### 3. Test Organization Pattern -Tests live alongside implementation: +Tests alongside implementation: - Feature: `feature.go` + `feature_test.go` - Integration: `feature_integration_test.go` - Scenario: `feature_scenario_test.go` @@ -55,10 +53,7 @@ graph TD ## Validation Architecture -Validates workflow configs before compilation. Two patterns: - -1. **Centralized** — `validation.go` -2. **Domain-specific** — dedicated files +Validates workflow configs before compilation. Centralized in `validation.go`, or domain-specific in dedicated files. ### Validation Flow @@ -94,8 +89,6 @@ graph TD #### Strict Mode: `strict_mode_validation.go` -Security/safety constraints in strict mode: - - `validateStrictMode()` — main orchestrator - `validateStrictPermissions()` — refuses write permissions - `validateStrictNetwork()` — requires explicit network config @@ -164,12 +157,12 @@ graph TD H --> K[normalizeLineEndings] ``` -**Sanitize** — fix characters causing security issues or breaking GitHub API: -- `sanitizeGitHubLabel()` — GitHub label requirements (no emoji, length limits) +**Sanitize** — fix chars that break security or GitHub API: +- `sanitizeGitHubLabel()` — label requirements (no emoji, length limits) - `sanitizeGitHubBranch()` — Git ref rules - `sanitizeGitHubIssueTitle()` — avoid problematic chars -**Normalize** — standardize format, no security implications: +**Normalize** — standardize format, no security implication: - `normalizeWhitespace()` — spaces, tabs, newlines - `normalizeLineEndings()` — CRLF → LF - `normalizeMarkdown()` — markdown formatting @@ -204,7 +197,7 @@ err := yaml.Unmarshal(data, &workflow) ## Safe Output Messages -Structured communication between agents and GitHub API operations. +Structured communication between agents and GitHub API. ### Message Categories @@ -250,7 +243,7 @@ graph LR ### Build System -Go implementation at `pkg/cli/actions_build_command.go`. No JS build scripts. +Go: `pkg/cli/actions_build_command.go`. No JS build scripts. **Commands**: - `make actions-build` — build all @@ -340,7 +333,7 @@ make update-golden # only when intentionally changing output ## Repo-Memory System -Persistent, git-backed storage for AI agents across workflow runs. State lives in dedicated git branches with auto-sync. +Persistent, git-backed storage across workflow runs. State lives in dedicated git branches with auto-sync. ### Architecture Overview @@ -366,11 +359,11 @@ graph TD ### Data Flow -1. **Clone**: `memory/{id}` branch to local directory -2. **Execution**: agent reads/writes files -3. **Upload**: directory as GitHub Actions artifact -4. **Download**: artifact and validate constraints -5. **Push**: commit and push to `memory/{id}` +1. Clone `memory/{id}` branch +2. Agent reads/writes files +3. Upload directory as artifact +4. Download artifact, validate constraints +5. Commit and push to `memory/{id}` ### Key Configuration @@ -391,7 +384,7 @@ repo-memory: ## Hierarchical Agent Management -Meta-orchestrator workflows manage multiple agents and workflows at scale. +Meta-orchestrators manage multiple agents and workflows at scale. ### Meta-Orchestrator Roles @@ -425,14 +418,14 @@ Brief description of the change ### End-to-End Feature Testing 1. Use `.github/workflows/dev.md` as test workflow -2. Add test scenarios as PR comments +2. Add scenarios as PR comments 3. Dev Hawk verifies behavior -4. Do not merge dev.md changes — it remains a reusable test harness +4. Do not merge dev.md changes — it stays a reusable test harness --- ## Scope Hints for Complex Workflows -Provide concrete constraints upfront. The more constraints, the faster and more accurate the generated workflow. +More upfront constraints → faster, more accurate generated workflow. ### Workflow-Type Guidance @@ -491,7 +484,7 @@ Before submitting a complex workflow request: ## PR Deduplication Protocol -Run before every PR — repeated closed attempts on the same topic waste CI and context. +Run before every PR — repeated closed attempts waste CI and context. ### Pre-flight Duplicate PR Check @@ -499,12 +492,12 @@ Search closed PRs via GitHub MCP `search_pull_requests`: 1. Extract 2–4 keywords from the feature/fix title. 2. Search e.g. `is:pr is:closed head:copilot/ ` or `is:pr is:closed `. -3. None found → proceed normally. -4. Any found → do [Prior Failure Analysis](#prior-failure-analysis) before writing code. +3. None found → proceed. +4. Any found → do [Prior Failure Analysis](#prior-failure-analysis) first. ### Prior Failure Analysis -At session start — before any code exploration: +Before any code exploration: 1. Read the closed PR description, review comments, and timeline. 2. Identify **root cause of closure**: @@ -512,8 +505,8 @@ At session start — before any code exploration: - CI/test failures → identify failing checks - Scope mismatch → clarify what was actually requested - Duplicate of another fix → link to that fix -3. Verify the new implementation will address the root cause. -4. Add a "## Prior Attempts" section to the new PR description: +3. Verify the new implementation addresses the root cause. +4. Add a "## Prior Attempts" section to the new PR: - Link(s) to prior closed PR(s) - Why each closed - What is different this time @@ -529,17 +522,17 @@ At session start — before any code exploration: ### Retry Limit Circuit Breaker -If **two or more** closed PRs already exist on the same topic: +If **two or more** closed PRs exist on the same topic: 1. **Do not open a third PR** without explicit human review. 2. Comment on the originating issue: - - List all prior closed PRs and close reasons + - List prior closed PRs and close reasons - Explain what changed in the new approach - - Request maintainer approval to proceed + - Request maintainer approval 3. Label the issue `copilot-retry-blocked`. -4. Wait for the maintainer to remove the label or approve before creating the PR. +4. Wait for the maintainer to remove the label or approve. -**Rationale:** Two failed attempts indicate a systemic problem (unclear requirements, missing context, design issue) that code alone cannot fix. +**Rationale:** Two failed attempts indicate a systemic problem (unclear requirements, missing context, design issue) code alone cannot fix. --- diff --git a/.github/aw/agentic-chat.md b/.github/aw/agentic-chat.md index 11c5de7ad48..fe66740f658 100644 --- a/.github/aw/agentic-chat.md +++ b/.github/aw/agentic-chat.md @@ -5,22 +5,22 @@ description: AI assistant for creating clear, actionable task descriptions for G # Agentic Task Description Assistant -You help users create clear, actionable task descriptions for GitHub Copilot coding agent that work with GitHub Agentic Workflows (gh-aw). +You help users create clear task descriptions for GitHub Copilot coding agent that work with GitHub Agentic Workflows (gh-aw). ## Required Knowledge -Load from the gh-aw repository: +Load from gh-aw: -1. **GitHub Agentic Workflows Instructions**: https://raw.githubusercontent.com/github/gh-aw/main/.github/aw/github-agentic-workflows.md +1. **Workflows Instructions**: https://raw.githubusercontent.com/github/gh-aw/main/.github/aw/github-agentic-workflows.md 2. **Dictation Instructions**: https://raw.githubusercontent.com/github/gh-aw/main/DICTATION.md ## Core Principles ### 1. Neutral Technical Tone -- Clear, direct language; no marketing +- Direct language; no marketing - No subjective adjectives ("great", "easy", "powerful") -### 2. Specification Generation Only +### 2. Specification Only - **DO NOT generate code** — pseudo-code only - Describe WHAT, not HOW - Include acceptance criteria @@ -31,8 +31,6 @@ Each step: what to do, inputs/outputs, constraints. ### 4. Task Description Format -Use this structure: - ```markdown # create a github agentic workflow that: [specific task goal] @@ -77,7 +75,7 @@ END FOR ## Output Format -Wrap the final task description in **5 backticks** for easy copy/paste into GitHub: +Wrap the final task description in **5 backticks** for copy/paste: `````markdown [Your complete task description here] @@ -87,12 +85,12 @@ Wrap the final task description in **5 backticks** for easy copy/paste into GitH ## Interaction Guidelines -1. **Clarify Requirements**: Ask about expected outcome, context (repo, issue numbers), constraints, and tools (GitHub API, web search, file editing, etc.) -2. **Validate Understanding**: Summarize before creating the spec -3. **Iterate**: Refine based on user feedback -4. **Stay Focused**: Spec, not implementation -5. **Reference Documentation**: Cite loaded instruction files when relevant -6. **Summarize Updates**: After the initial request, summarize latest changes rather than re-reading the full markdown +1. **Clarify**: Ask about expected outcome, context (repo, issue numbers), constraints, and tools (GitHub API, web search, file editing). +2. **Validate**: Summarize before creating the spec. +3. **Iterate**: Refine on feedback. +4. **Stay Focused**: Spec, not implementation. +5. **Cite**: Reference loaded instruction files when relevant. +6. **Summarize updates** after the initial request rather than re-reading the full markdown. ## Terminology @@ -103,9 +101,9 @@ Use gh-aw terms (see dictation instructions): - "gh-aw" (not "ghaw"/"G H A W") - Hyphenated: "safe-outputs", "cache-memory", "max-turns" -## What You Should NOT Do +## Do Not -- Do not over-specify — balance clarity with flexibility -- Do not ignore user questions — always clarify first +- Over-specify — balance clarity with flexibility +- Ignore user questions — clarify first -**Final Step**: Compile the generated workflow in strict mode and fix any errors or warnings before returning. +**Final Step**: Compile the workflow in strict mode and fix errors/warnings before returning.