diff --git a/.github/workflows/daily-news.lock.yml b/.github/workflows/daily-news.lock.yml index 2cf48f3ddc..fdd31401ef 100644 --- a/.github/workflows/daily-news.lock.yml +++ b/.github/workflows/daily-news.lock.yml @@ -1497,6 +1497,62 @@ jobs: - Include a short haiku at the end of the report to help orient the team to the season of their work. + ## 📝 Report Formatting Guidelines + + Follow these formatting guidelines to create well-structured, readable news reports: + + ### 1. Header Levels + **Use h3 (###) or lower for all headers in your news report to maintain proper document hierarchy.** + + When creating your news report: + - Use `###` (h3) for main sections (e.g., "### Top News", "### Trend Analysis") + - Use `####` (h4) for subsections (e.g., "#### Recent Releases", "#### Community Engagement") + - Never use `##` (h2) or `#` (h1) in the report body - these are reserved for titles + + ### 2. Progressive Disclosure + **Wrap detailed news analysis and long article sections in `
Section Name` tags to improve readability.** + + Use collapsible sections for: + - Detailed article analysis + - Verbose commit logs or detailed change descriptions + - Additional news items that provide extra context + - Extended lists of issues or pull requests + + Always keep critical information visible: + - Brief summary of top news items + - Key headlines with links + - High-level trend insights + - Important recommendations or takeaways + + Example structure: + ```markdown +
+ Full News Analysis + + [Long detailed content here...] + +
+ ``` + + ### 3. Suggested Report Structure + + Structure your news report with these sections: + + 1. **Brief Summary** (always visible): 1-2 paragraphs highlighting the most important news + 2. **Key Headlines** (always visible): Top 3-5 headlines with links to issues/PRs/releases + 3. **📈 Trend Analysis** (always visible): Include the 2 required charts with brief analysis + 4. **Detailed Article Analysis** (in `
` tags): Deep dive into specific items + 5. **Additional News Items** (in `
` tags): Secondary stories and updates + 6. **Recommendations & Takeaways** (always visible): Actionable insights for the team + + ### Design Principles + + Your reports should: + - **Build trust through clarity**: Most important info immediately visible + - **Exceed expectations**: Add helpful context, summaries, and insights + - **Create delight**: Use progressive disclosure to reduce overwhelm + - **Maintain consistency**: Follow the same patterns as other reporting workflows + - In a note at the end of the report, include a log of: * All web search queries you used (if any) * All files you read from `/tmp/gh-aw/daily-news-data/` diff --git a/.github/workflows/daily-news.md b/.github/workflows/daily-news.md index 9ad55f2bad..dd992609f7 100644 --- a/.github/workflows/daily-news.md +++ b/.github/workflows/daily-news.md @@ -463,6 +463,62 @@ If insufficient data is available (less than 7 days): - Include a short haiku at the end of the report to help orient the team to the season of their work. +## 📝 Report Formatting Guidelines + +Follow these formatting guidelines to create well-structured, readable news reports: + +### 1. Header Levels +**Use h3 (###) or lower for all headers in your news report to maintain proper document hierarchy.** + +When creating your news report: +- Use `###` (h3) for main sections (e.g., "### Top News", "### Trend Analysis") +- Use `####` (h4) for subsections (e.g., "#### Recent Releases", "#### Community Engagement") +- Never use `##` (h2) or `#` (h1) in the report body - these are reserved for titles + +### 2. Progressive Disclosure +**Wrap detailed news analysis and long article sections in `
Section Name` tags to improve readability.** + +Use collapsible sections for: +- Detailed article analysis +- Verbose commit logs or detailed change descriptions +- Additional news items that provide extra context +- Extended lists of issues or pull requests + +Always keep critical information visible: +- Brief summary of top news items +- Key headlines with links +- High-level trend insights +- Important recommendations or takeaways + +Example structure: +```markdown +
+Full News Analysis + +[Long detailed content here...] + +
+``` + +### 3. Suggested Report Structure + +Structure your news report with these sections: + +1. **Brief Summary** (always visible): 1-2 paragraphs highlighting the most important news +2. **Key Headlines** (always visible): Top 3-5 headlines with links to issues/PRs/releases +3. **📈 Trend Analysis** (always visible): Include the 2 required charts with brief analysis +4. **Detailed Article Analysis** (in `
` tags): Deep dive into specific items +5. **Additional News Items** (in `
` tags): Secondary stories and updates +6. **Recommendations & Takeaways** (always visible): Actionable insights for the team + +### Design Principles + +Your reports should: +- **Build trust through clarity**: Most important info immediately visible +- **Exceed expectations**: Add helpful context, summaries, and insights +- **Create delight**: Use progressive disclosure to reduce overwhelm +- **Maintain consistency**: Follow the same patterns as other reporting workflows + - In a note at the end of the report, include a log of: * All web search queries you used (if any) * All files you read from `/tmp/gh-aw/daily-news-data/` diff --git a/pkg/cli/templates/create-agentic-workflow.md b/pkg/cli/templates/create-agentic-workflow.md index 161444b155..1b31386fde 100644 --- a/pkg/cli/templates/create-agentic-workflow.md +++ b/pkg/cli/templates/create-agentic-workflow.md @@ -181,7 +181,7 @@ DO NOT ask all these questions at once; instead, engage in a back-and-forth conv - 📋 **DO NOT include other fields with good defaults** - Let the compiler use sensible defaults unless customization is needed. - Apply security best practices: - Default to `permissions: read-all` and expand only if necessary. - - Prefer `safe-outputs` (`create-issue`, `add-comment`, `create-pull-request`, `create-pull-request-review-comment`, `update-issue`) over granting write perms. + - Prefer `safe-outputs` (`create-issue`, `add-comment`, `create-pull-request`, `create-pull-request-review-comment`, `update-issue`, `dispatch-workflow`) over granting write perms. - For custom write operations to external services (email, Slack, webhooks), use `safe-outputs.jobs:` to create custom safe output jobs. - Constrain `network:` to the minimum required ecosystems/domains. - Use sanitized expressions (`${{ needs.activation.outputs.text }}`) instead of raw event text. diff --git a/pkg/cli/templates/create-shared-agentic-workflow.md b/pkg/cli/templates/create-shared-agentic-workflow.md index 76e0675728..577bc3660c 100644 --- a/pkg/cli/templates/create-shared-agentic-workflow.md +++ b/pkg/cli/templates/create-shared-agentic-workflow.md @@ -34,7 +34,7 @@ You are a conversational chat agent that interacts with the user to design secur **Move Write Operations to Safe Outputs** - Never grant direct write permissions in shared components - Use `safe-outputs:` configuration for all write operations -- Common safe outputs: `create-issue`, `add-comment`, `create-pull-request`, `update-issue` +- Common safe outputs: `create-issue`, `add-comment`, `create-pull-request`, `update-issue`, `dispatch-workflow` - Let consuming workflows decide which safe outputs to enable **Process Agent Output in Safe Jobs** diff --git a/pkg/cli/templates/github-agentic-workflows.md b/pkg/cli/templates/github-agentic-workflows.md index 0724608609..f350e65b03 100644 --- a/pkg/cli/templates/github-agentic-workflows.md +++ b/pkg/cli/templates/github-agentic-workflows.md @@ -568,6 +568,14 @@ The YAML frontmatter supports these fields: target-repo: "owner/repo" # Optional: cross-repository ``` Publishes workflow artifacts to an orphaned git branch for persistent storage. Default allowed extensions include common non-executable types. Maximum file size is 50MB (51200 KB). + - `dispatch-workflow:` - Trigger other workflows with inputs + ```yaml + safe-outputs: + dispatch-workflow: + workflows: [workflow-name] # Required: list of workflow names to allow + max: 3 # Optional: max dispatches (default: 1, max: 3) + ``` + Triggers other agentic workflows in the same repository using workflow_dispatch. Agent output includes `workflow_name` (without .md extension) and optional `inputs` (key-value pairs). Not supported for cross-repository operations. - `create-code-scanning-alert:` - Generate SARIF security advisories ```yaml safe-outputs: