improve agentics

Author: dsyme

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

@@ -16,7 +16,7 @@ This is a **dispatcher agent** that routes your request to the appropriate speci
 - **Debugging workflows**: Routes to `debug` prompt  
 - **Upgrading workflows**: Routes to `upgrade-agentic-workflows` prompt
 - **Creating shared components**: Routes to `create-shared-agentic-workflow` prompt
-- **Fixing Dependabot PRs**: Routes to `dependabot` prompt — use this when Dependabot opens PRs that modify generated manifest files (`.github/workflows/package.json`, `.github/workflows/requirements.txt`, `.github/workflows/go.mod`). Never merge those PRs directly; instead update the source `.md` files and rerun `gh aw compile --dependabot` to bundle all fixes
+- **Fixing Dependabot PRs**: Routes to `dependabot` prompt  -  use this when Dependabot opens PRs that modify generated manifest files (`.github/workflows/package.json`, `.github/workflows/requirements.txt`, `.github/workflows/go.mod`). Never merge those PRs directly; instead update the source `.md` files and rerun `gh aw compile --dependabot` to bundle all fixes
 
 Workflows may optionally include:
 

.github/agents/contribution-checker.agent.md

@@ -3,7 +3,7 @@ description: Evaluate a single PR against the target repository's CONTRIBUTING.m
 user-invokable: false
 ---
 
-# Contribution Checker — Single PR Evaluator
+# 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.
 
@@ -21,7 +21,7 @@ Fetch the target repository's contributing guidelines. Look for these files in o
 
 If none exist, return a single row with verdict `❓` and 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.
+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.
 
 ## Step 2: Gather PR Data
 
@@ -34,38 +34,38 @@ For the given PR, retrieve:
 
 Before running the checklist, do a deep dive into both the **target repository** and the **PR branch** to build enough context for high-quality, specific feedback:
 
-1. **Understand the codebase** — browse the target repo's directory structure, README, and architecture docs. Identify the project's tech stack, module layout, and conventions (e.g., where tests live, how modules are organized, what frameworks are used).
-2. **Understand the changed area** — for each file touched by the PR, read the surrounding code (not just the diff). Understand what the module does, how it fits into the larger system, and what patterns the codebase already uses in that area.
-3. **Check for related issues** — if the PR body references an issue, read that issue to understand the original requirements and acceptance criteria.
-4. **Check for existing tests** — look at the test directory/files adjacent to the changed code. Understand the testing patterns and frameworks the project uses so your feedback and agentic prompts reference the right tools and conventions.
-5. **Check for duplicated effort** — search for open PRs that touch the same files or address the same issue to flag potential conflicts.
+1. **Understand the codebase**  -  browse the target repo's directory structure, README, and architecture docs. Identify the project's tech stack, module layout, and conventions (e.g., where tests live, how modules are organized, what frameworks are used).
+2. **Understand the changed area**  -  for each file touched by the PR, read the surrounding code (not just the diff). Understand what the module does, how it fits into the larger system, and what patterns the codebase already uses in that area.
+3. **Check for related issues**  -  if the PR body references an issue, read that issue to understand the original requirements and acceptance criteria.
+4. **Check for existing tests**  -  look at the test directory/files adjacent to the changed code. Understand the testing patterns and frameworks the project uses so your feedback and agentic prompts reference the right tools and conventions.
+5. **Check for duplicated effort**  -  search for open PRs that touch the same files or address the same issue to flag potential conflicts.
 
-This research ensures the comment and agentic prompt you generate are **specific to the actual codebase** — referencing real file paths, real test patterns, and real conventions rather than generic advice.
+This research ensures the comment and agentic prompt you generate are **specific to the actual codebase**  -  referencing real file paths, real test patterns, and real conventions rather than generic advice.
 
 ## 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.
 
-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`.
-3. **Focused** — Does the PR do one thing, or does it mix unrelated changes? Answer `yes` or `no`.
-4. **New deps** — Does the diff add a new entry to a dependency manifest (package.json, go.mod, Cargo.toml, etc.)? Answer `yes` or `no`.
-5. **Has tests** — Does the diff include changes to test files? Answer `yes` or `no`.
-6. **Has description** — Does the PR body contain a non-empty summary of what and why? Answer `yes` or `no`.
-7. **Diff size** — Total lines changed (additions + deletions). Report the number.
+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`.
+3. **Focused**  -  Does the PR do one thing, or does it mix unrelated changes? Answer `yes` or `no`.
+4. **New deps**  -  Does the diff add a new entry to a dependency manifest (package.json, go.mod, Cargo.toml, etc.)? Answer `yes` or `no`.
+5. **Has tests**  -  Does the diff include changes to test files? Answer `yes` or `no`.
+6. **Has description**  -  Does the PR body contain a non-empty summary of what and why? Answer `yes` or `no`.
+7. **Diff size**  -  Total lines changed (additions + deletions). Report the number.
 
 ## Step 4: Apply Verdict Rules
 
-- **🔴 Off-Guidelines** — on-topic is `no`, OR follows-process is `no` with a clear violation.
-- **⚠️ Needs Focus** — focused is `no` (mixes unrelated changes).
-- **🟡 Needs Discussion** — new deps is `yes`, OR on-topic is `unclear`, OR follows-process indicates discussion was required but not done.
-- **🟢 Aligned** — none of the above triggered.
+- **🔴 Off-Guidelines**  -  on-topic is `no`, OR follows-process is `no` with a clear violation.
+- **⚠️ Needs Focus**  -  focused is `no` (mixes unrelated changes).
+- **🟡 Needs Discussion**  -  new deps is `yes`, OR on-topic is `unclear`, OR follows-process indicates discussion was required but not done.
+- **🟢 Aligned**  -  none of the above triggered.
 
 ## Step 5: Assign Quality Signal
 
-- **`spam`** — 🔴 with no description and no clear purpose.
-- **`needs-work`** — ⚠️, or 🟡, or missing tests, or missing description.
-- **`lgtm`** — 🟢 with tests and description present.
+- **`spam`**  -  🔴 with no description and no clear purpose.
+- **`needs-work`**  -  ⚠️, or 🟡, or missing tests, or missing description.
+- **`lgtm`**  -  🟢 with tests and description present.
 
 ## Output Format
 
@@ -104,34 +104,34 @@ Where:
 
 The `comment` field is a markdown string posted to the PR to help the contributor improve their submission. It 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. **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.
 
 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.
 
 Example for a `needs-work` PR:
 
 ```markdown
-Hey @alice 👋 — thanks for working on the auth refactor! Here are a few things that would help get this across the finish line:
+Hey @alice 👋  -  thanks for working on the auth refactor! Here are a few things that would help get this across the finish line:
 
-- **Add tests** — the new rate-limiting logic in `src/auth/limiter.ts` doesn't have coverage yet. Unit tests for the happy path and the throttled case would go a long way.
-- **Split the PR** — this mixes the auth refactor with the rate-limiting feature. Consider separating them so reviewers can focus on one thing at a time.
+- **Add tests**  -  the new rate-limiting logic in `src/auth/limiter.ts` doesn't have coverage yet. Unit tests for the happy path and the throttled case would go a long way.
+- **Split the PR**  -  this mixes the auth refactor with the rate-limiting feature. Consider separating them so reviewers can focus on one thing at a time.
 
 If you'd like a hand, you can assign this prompt to your coding agent:
 
 ` `` prompt
 Add unit tests for the rate-limiting middleware in src/auth/limiter.ts.
 Cover the following scenarios:
-1. Request under the limit — should pass through.
-2. Request at the limit — should return 429.
+1. Request under the limit  -  should pass through.
+2. Request at the limit  -  should return 429.
 3. Limit reset after window expires.
 ` ``
 ```
 
 ## 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.
+- **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.

.github/workflows/daily-repo-goals.md

@@ -42,7 +42,7 @@ You are a repository maintainer for `${{ github.repository }}`. Your job is to k
 
 Work in two phases each run. Always do Phase 1. Then do Phase 2 only if Phase 1 found no problems requiring a PR.
 
-## Phase 1 — Consistency Check
+## Phase 1  -  Consistency Check
 
 Check the repository for consistency across three layers:
 
@@ -58,7 +58,7 @@ If any glaring mutual inconsistencies are found, create a pull request that fixe
 
 Then proceed to Phase 2. Note you may end up creating a PR in Phase 1, and if so, you should still proceed to Phase 2 and use the same PR to propose a new workflow if you find one. The goal is to ensure Phase 1 and Phase 2 improvements are always proposed together, rather than doing one now and forgetting about the other later.
 
-## Phase 2 — Workflow Discovery
+## Phase 2  -  Workflow Discovery
 
 Your goal is to find one new high-value, general-purpose workflow from Peli's Agent Factory that would be a good addition to this repository.
 

.github/workflows/import-workflow.md

@@ -183,7 +183,7 @@ The PR description should include:
 
 ## Important Guidelines
 
-- Always review and generalize imported workflows — do not blindly copy project-specific content
+- Always review and generalize imported workflows  -  do not blindly copy project-specific content
 - Match the documentation style of existing pages in `docs/`
 - Keep the workflow prompt clear, actionable, and concise
 - Preserve security-first design: minimal permissions, explicit network access, safe outputs

README.md

@@ -60,7 +60,6 @@ You can use the "/plan" agent to turn the reports into actionable issues which c
 - [⚡ Daily Progress](docs/daily-progress.md) - Automated daily feature development following a structured roadmap
 - [🧪 Daily Test Coverage Improver](docs/daily-test-improver.md) - Improve test coverage by adding meaningful tests to under-tested areas
 - [⚡ Daily Performance Improver](docs/daily-perf-improver.md) - Analyze and improve code performance through benchmarking and optimization
-- [🔥 Daily Backlog Burner](docs/daily-backlog-burner.md) - Systematically manage and reduce backlog through strategic cleanup
 
 ## Security Workflows
 

docs/ai-moderator.md

@@ -2,71 +2,54 @@
 
 > For an overview of all available workflows, see the [main README](../README.md).
 
-The [AI Moderator workflow](../workflows/ai-moderator.md?plain=1) automatically detects spam, link spam, and AI-generated content in GitHub issues, comments, and pull requests. This workflow helps maintain quality discussions and protect your repository from malicious or low-quality contributions.
+**Automatically detect spam, link spam, and AI-generated content in GitHub issues, comments, and pull requests**
+
+The [AI Moderator workflow](../workflows/ai-moderator.md?plain=1) helps maintain quality discussions and protect your repository from malicious or low-quality contributions by automatically moderating incoming content.
 
 ## Installation
 
-````bash
+```bash
 # Install the 'gh aw' extension
 gh extension install github/gh-aw
 
 # Add the workflow to your repository
 gh aw add-wizard githubnext/agentics/ai-moderator
-````
+```
 
 This walks you through adding the workflow to your repository.
 
-You must also [choose a coding agent](https://github.github.com/gh-aw/reference/engines/) and add an API key secret for the agent to your repository.
-
-You can't start a run of this workflow directly as it is triggered automatically when issues, comments, or pull requests are created.
-
 ## How It Works
 
-````mermaid
+```mermaid
 graph LR
     A[New Issue/PR/Comment] --> B[Analyze Content]
     B --> C{Spam or<br/>AI-Generated?}
     C -->|Spam| D[Add Label & Hide]
     C -->|AI-Generated| E[Add ai-generated Label]
     C -->|Clean| F[Add ai-inspected Label]
-````
-
-## Configuration
+```
 
-This workflow works out of the box with sensible defaults. You can customize:
+The workflow reads new issues, comments, and pull request diffs, then applies appropriate labels (`spam`, `link-spam`, `ai-generated`, or `ai-inspected`). It can hide comments detected as spam. Requires `issues: write` and `pull-requests: write` permissions for full functionality.
 
-- The labels to apply for different detection types (spam, link-spam, ai-generated, ai-inspected)
-- The user roles that are skipped (defaults to admins, maintainers, write access, and triage)
-- The bots to skip (defaults to github-actions and copilot)
-- Rate limiting settings to control how often the workflow runs
-- Detection criteria and thresholds in the workflow prompt
+## Usage
 
-After editing run `gh aw compile` to update the workflow and commit all changes to the default branch.
-
-## What it reads from GitHub
+This workflow triggers automatically when issues, comments, or pull requests are created—you cannot start it manually.
 
-- New issues and their content
-- Comments on issues and pull requests
-- Pull request diffs and file changes
-- Repository context to evaluate content relevance
-- User information and roles
+### Configuration
 
-## What it creates
+The workflow works out of the box with sensible defaults. You can customize:
 
-- Adds labels to issues and pull requests (`spam`, `link-spam`, `ai-generated`, or `ai-inspected`)
-- Hides comments that are detected as spam
-- Requires `issues: write` and `pull-requests: write` permissions (note: the workflow is configured with read-only by default, so you'll need to adjust permissions if you want it to take action)
+- Labels to apply for different detection types
+- User roles that are skipped (defaults to admins, maintainers, write access, and triage)
+- Bots to skip (defaults to github-actions and copilot)
+- Rate limiting settings
+- Detection criteria and thresholds
 
-## What web searches it performs
-
-This workflow does not perform web searches.
+After editing run `gh aw compile` to update the workflow and commit all changes to the default branch.
 
-## Human in the loop
+### Human in the Loop
 
 - Review labels applied to ensure accurate spam detection
 - Monitor for false positives and adjust detection criteria if needed
 - Override moderation decisions when the AI makes mistakes
-- Validate hidden comments and unhide legitimate content if necessary
-- Adjust the workflow configuration based on your repository's needs
-- Consider exempting trusted contributors from moderation if desired
-- Disable or uninstall the workflow if moderation automation is not providing value
+- Unhide legitimate content if necessary