From ac2e9972b3204afa683d202d3df7ec09b916dc5e Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 10 Jun 2026 03:08:39 +0000 Subject: [PATCH] [caveman] Trim verbose prose in memory/mcp-clis/messages/network docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Apply caveman optimization to four .github/aw/ instruction files — fix duplicate cells in memory tradeoff tables and condense filler prose in section intros and notes. Schema tables, YAML examples, and compiler constraints unchanged. Co-Authored-By: Claude Opus 4.8 --- .github/aw/mcp-clis.md | 33 ++++++++++++++------------------- .github/aw/memory.md | 16 ++++++++-------- .github/aw/messages.md | 6 +++--- .github/aw/network.md | 2 +- 4 files changed, 26 insertions(+), 31 deletions(-) diff --git a/.github/aw/mcp-clis.md b/.github/aw/mcp-clis.md index 4f65554fb69..ec05af78a8a 100644 --- a/.github/aw/mcp-clis.md +++ b/.github/aw/mcp-clis.md @@ -4,18 +4,17 @@ description: MCP CLI command usage guidance and JSON payload patterns # MCP CLI Usage -The MCP CLI feature exposes mounted MCP servers as shell commands on `PATH` and provides a consistent command interface for tool calls. -They are enabled by `tools.cli-proxy: true`. +MCP CLI exposes mounted MCP servers as shell commands on `PATH`. Enabled by `tools.cli-proxy: true`. -> **IMPORTANT**: For `safeoutputs` and `mcpscripts`, **always use the CLI commands** instead of the equivalent MCP tools. The CLI wrappers are the preferred interface — do **not** call their MCP tools directly even though they may appear in your tool list. +> **IMPORTANT**: For `safeoutputs` and `mcpscripts`, **always use the CLI commands** instead of the equivalent MCP tools — do **not** call their MCP tools directly even if they appear in your tool list. > -> For `safeoutputs`, treat every successful command as a real write-intent declaration. Do **not** use `safeoutputs` for exploratory probing, auth checks, placeholder payloads, repeated "try again" variants, or manual runtime experiments. When you need a safe-output, emit the final intended call once. If you are not ready to perform the real action, use `noop` or `report_incomplete` instead. +> For `safeoutputs`, treat every successful command as a real write-intent declaration. Do **not** use it for exploratory probing, auth checks, placeholder payloads, retries with variants, or runtime experiments. Emit the final intended call once. If not ready, use `noop` or `report_incomplete`. > -> For all other servers listed here, they are **only** available as CLI commands and are **not** available as MCP tools. +> All other servers listed here are **only** available as CLI commands, not MCP tools. ## How to use -Each server is a standalone executable on your `PATH`. Invoke it from bash like any other shell command: +Each server is a standalone executable on `PATH`. Invoke it from bash: ```bash # Call a tool — pass arguments as --name value pairs @@ -42,7 +41,7 @@ mcpscripts mcpscripts-gh --args "pr list --repo owner/repo --limit 5" Passing multiple or complex arguments (preferred): -**Preferred approach for any tool call with multiple or complex arguments**: supply a JSON object on stdin using `.` as the sentinel. The bridge parses stdin as the argument object, preserving all native types (numbers, booleans, arrays) without shell-quoting issues. +Supply a JSON object on stdin using `.` as the sentinel. The bridge parses stdin as the argument object, preserving native types (numbers, booleans, arrays) without shell-quoting issues. ```bash # Full argument payload as JSON via printf pipe @@ -54,18 +53,14 @@ printf '{"title":"Fix: something","body":"Details here","labels":["bug","priorit | safeoutputs create_issue . ``` -If pipes are blocked by bash policy, write JSON to a file and use redirection with `.` (for example: `safeoutputs create_pull_request . < /tmp/payload.json`). - -> **Why prefer JSON payload mode?** -> - Preserves native types and avoids shell quoting/escaping pitfalls -> - Supports both pipe and file-redirection input with the same `.` sentinel +If pipes are blocked, write JSON to a file and use redirection with `.` (e.g. `safeoutputs create_pull_request . < /tmp/payload.json`). ## Notes -- **Prefer JSON payload mode** (`. < file` or `printf '{...}' | server tool .`) for any call with multiple arguments or complex values -- All parameters can also be passed as `--name value` pairs; boolean flags can be set with `--flag` (no value) to mean `true` -- Use `.` as the only argument to parse stdin as a JSON object (all parameters supplied at once) -- Parameter names with hyphens or underscores are interchangeable (e.g. `issue-number` and `issue_number` both work) -- Output is printed to stdout; errors are printed to stderr with a non-zero exit code -- Run the CLI commands inside a `bash` tool call — they are shell executables, not MCP tools -- These CLI commands are read-only and cannot be modified by the agent +- **Prefer JSON payload mode** (`. < file` or `printf '{...}' | server tool .`) for multi-argument or complex calls +- Parameters also accept `--name value` pairs; boolean flags use `--flag` (no value) for `true` +- `.` as sole argument parses stdin as a JSON object +- Hyphens and underscores in parameter names are interchangeable (`issue-number` == `issue_number`) +- Output goes to stdout; errors to stderr with non-zero exit +- Run inside a `bash` tool call — these are shell executables, not MCP tools +- Read-only; cannot be modified by the agent diff --git a/.github/aw/memory.md b/.github/aw/memory.md index b274f585874..0067b6d7638 100644 --- a/.github/aw/memory.md +++ b/.github/aw/memory.md @@ -4,7 +4,7 @@ description: Guide for choosing the right persistent memory strategy in agentic # Persistent Memory in Agentic Workflows -Consult this file when designing a workflow that needs to **persist state across runs** — deduplication, incremental processing, cross-run context, or knowledge accumulation. +For workflows that **persist state across runs** — deduplication, incremental processing, cross-run context, or knowledge accumulation. > ⚠️ **`repo-memory` does NOT mean "cache-memory"**. They are two distinct tools with different backends, tradeoffs, and use cases. `cache-memory` is almost always the right first choice. @@ -257,10 +257,10 @@ The compiler automatically creates a separate `push_repo_memory` job with `conte | ✅ Pros | ❌ Cons | |---|---| | Persists indefinitely (no expiry) | Produces Git commits — repository noise | -| Auditable: Git history shows every change | Produces Git commits — repository noise | -| Survives cache invalidation | Slower: requires Git clone + push | -| Human-readable via GitHub branch UI | Not available for Copilot engine (requires GitHub tools) | -| Can target a different repository | More complex setup | +| Auditable: Git history shows every change | Slower: requires Git clone + push | +| Survives cache invalidation | Not available for Copilot engine (requires GitHub tools) | +| Human-readable via GitHub branch UI | More complex setup | +| Can target a different repository | | --- @@ -292,9 +292,9 @@ Files follow GitHub Wiki Markdown conventions: use `[[Page Name]]` syntax for in | ✅ Pros | ❌ Cons | |---|---| | Browsable in the GitHub Wiki UI | Produces Git commits to wiki repo | -| Great for human-readable knowledge bases | Produces Git commits to wiki repo | -| Standard Markdown with wiki link syntax | Restricted to `.md` files in practice | -| Separate from main repo history | Less suitable for structured JSON state | +| Great for human-readable knowledge bases | Restricted to `.md` files in practice | +| Standard Markdown with wiki link syntax | Less suitable for structured JSON state | +| Separate from main repo history | | --- diff --git a/.github/aw/messages.md b/.github/aw/messages.md index e26f4415a95..7b233c23209 100644 --- a/.github/aw/messages.md +++ b/.github/aw/messages.md @@ -4,13 +4,13 @@ description: Style guide for workflow status messages (all safe-outputs.messages # Workflow Status Messages -Apply this guide when writing `safe-outputs.messages` in any workflow. Messages appear in GitHub issues, PR comments, and discussions. +For writing `safe-outputs.messages`. Messages appear in GitHub issues, PR comments, and discussions. ## Rules -**Tone:** Plain and professional. Describe what the workflow does or what happened. No casual phrases ("Mission accomplished!", "Knowledge acquired!"), no dramatic language ("interrupted!", "crashed!"), no excitement punctuation (`!!`). +**Tone:** Plain and professional. No casual phrases ("Mission accomplished!"), no dramatic language ("interrupted!"), no excitement punctuation (`!!`). -**Emoji:** One per message, at the start. Use the same emoji across `run-started`, `run-success`, `run-failure`, and `footer` for consistency. Do not append trailing emojis (`🏆`, `✅`, `📋`, etc.). +**Emoji:** One per message, at the start. Use the same emoji across `run-started`, `run-success`, `run-failure`, and `footer`. No trailing emojis. Emoji by domain: 🔍 search · 📐 architecture · 🔬 analysis/security · 📦 dependencies · 📝 docs · 🧪 testing · 🚀 release · 👀 review diff --git a/.github/aw/network.md b/.github/aw/network.md index 7628810ea7d..50632182064 100644 --- a/.github/aw/network.md +++ b/.github/aw/network.md @@ -4,7 +4,7 @@ description: Network access configuration reference for gh-aw workflows — vali # Network Access Configuration -Use the `network` frontmatter field to control which domains an AI engine can reach during a workflow run. All traffic is enforced by the Agent Workflow Firewall (AWF). +The `network` frontmatter controls which domains an AI engine can reach. Enforced by the Agent Workflow Firewall (AWF). ## Quick Reference