[docs] Consolidate developer specifications into instructions file (v9.14)

scratchpad/actions.md

@@ -41,7 +41,7 @@ Create a custom actions system that:
 - Provides versioning through Git tags/releases
 - Enables reuse via `uses: ./actions/{action-name}`
 - Supports independent testing and validation
-- Leverages existing bundler infrastructure from workflow compilation
+- Reuses existing bundler infrastructure from workflow compilation
 
 ## Architecture
 
@@ -320,7 +320,7 @@ outputContent := filesRegex.ReplaceAllString(
 
 ### Decision 1: Reuse Workflow Bundler Infrastructure
 
-**Decision**: Leverage existing `workflow.GetJavaScriptSources()` instead of creating separate bundling system.
+**Decision**: Reuse existing `workflow.GetJavaScriptSources()` instead of creating a separate bundling system.
 
 **Rationale**:
 - Eliminates code duplication
@@ -912,7 +912,7 @@ jobs:
 2. **Fallback strategy**: If action path not found, automatically falls back to inline mode
 3. **Backward compatibility**: Default mode is inline, no breaking changes to existing workflows
 4. **Token mapping**: Custom actions use `token` input instead of `github-token` parameter
-5. **Reuse existing infrastructure**: Leverages the same script registry and bundler used for inline mode
+5. **Reuse existing infrastructure**: Uses the same script registry and bundler as inline mode
 
 ### Integration Points
 

scratchpad/agents/hierarchical-agents.md

@@ -243,7 +243,7 @@ Meta-orchestrators provide detailed reports including:
 - Coordinate with related campaigns
 - Adjust priorities based on portfolio analysis
 
-**Leverage cross-campaign coordination:**
+**Use cross-campaign coordination:**
 - Avoid conflicts by checking coordination notes
 - Share resources with related campaigns
 - Sequence work appropriately

scratchpad/dev.md

@@ -1,7 +1,7 @@
 # Developer Instructions
 
-**Version**: 9.13
-**Last Updated**: 2026-05-21
+**Version**: 9.14
+**Last Updated**: 2026-05-22
 **Purpose**: Consolidated development guidelines for GitHub Agentic Workflows
 
 This document consolidates specifications from the scratchpad directory into unified developer instructions. It provides architecture patterns, security guidelines, code organization rules, and testing practices.
@@ -2974,6 +2974,7 @@ These files are loaded automatically by compatible AI tools (e.g., GitHub Copilo
 ---
 
 **Document History**:
+- v9.14 (2026-05-22): Maintenance tone scan — fixed 10 "leverage" tone issues across 7 spec files. "Leverage" is corporate-speak that translates to concrete verbs like "use", "reuse", or "adopt" in context: `serena-tools-analysis.md` (2 fixes: heading "### 3. Leverage Unused Capabilities"→"### 3. Use Unused Capabilities" line 218; "doesn't fully leverage their language-aware capabilities"→"doesn't fully use their language-aware capabilities" line 368); `mods/jsonschema-go.md` (2 fixes: "leveraging Go 1.18+ generics for compile-time type safety"→"using Go 1.18+ generics for compile-time type safety" line 53; "3. **Leverage Schema Descriptions**"→"3. **Use Schema Descriptions**" line 147); `gastown.md` (1 fix: "Leverage GitHub as communication layer for gastown agents"→"Use GitHub as the communication layer for gastown agents" line 944); `actions.md` (3 fixes: "Leverages existing bundler infrastructure from workflow compilation"→"Reuses existing bundler infrastructure from workflow compilation" line 44; "**Decision**: Leverage existing `workflow.GetJavaScriptSources()` instead of creating separate bundling system."→"**Decision**: Reuse existing `workflow.GetJavaScriptSources()` instead of creating a separate bundling system." line 323; "**Reuse existing infrastructure**: Leverages the same script registry and bundler used for inline mode"→"**Reuse existing infrastructure**: Uses the same script registry and bundler as inline mode" line 915 — the bullet already led with "Reuse", so "Leverages" was redundant filler); `agents/hierarchical-agents.md` (1 fix: "**Leverage cross-campaign coordination:**"→"**Use cross-campaign coordination:**" line 246); `mdflow.md` (1 fix: "Leverage mdflow's simplicity in gh-aw context"→"Adopt mdflow's minimal-configuration approach in the gh-aw context" line 1355 — "simplicity" is subjective; replaced with the concrete property already used elsewhere in the file); `github-mcp-access-control-specification.md` (1 fix: "Both leverage MCP Gateway's extensible configuration format"→"Both use MCP Gateway's extensible configuration format" line 108). Coverage: 64 spec files (no new files).
 - v9.13 (2026-05-21): Maintenance tone scan — fixed 8 tone issues across 6 spec files: `serena-tools-analysis.md` (2 fixes: "# Serena Tools Usage - Deep Statistical Analysis"→"# Serena Tools Usage - Statistical Analysis" line 1 — "Deep" is redundant when "Statistical Analysis" follows, matches v9.7 "Complete deep dive"→"Complete statistical analysis" pattern; "rather than deep language service features"→"rather than language service features" line 181 — removed subjective intensifier, matches v9.7 "deep exploration"→"multi-step exploration" pattern); `mdflow.md` (2 fixes: "**Status**: Deep Technical Analysis"→"**Status**: Technical Analysis" line 5; "This document provides a deep technical analysis"→"This document provides a technical analysis" line 11 — "deep" is subjective, matches v5.7 "Deep Research Comparison"→"Technical Comparison" pattern); `engine-architecture-review.md` (1 fix: "**Scope**: Deep review of agentic engine interface and implementations"→"**Scope**: Detailed review of agentic engine interface and implementations" line 5 — matches v3.8 "Deep analysis"→"Detailed analysis" pattern); `engine-review-summary.md` (1 fix: "Completed deep review of the agentic engine architecture"→"Completed a detailed review of the agentic engine architecture" line 5 — same v3.8 pattern); `ubuntulatest.md` (1 fix: "due to the extensive software list"→"due to the size of the software list" line 350 — replaced subjective "extensive" with concrete "size", matches v9.10 "Due to the extensive nature of..."→"Given the number of..." pattern). Also updated dev.md Related Documentation description for `serena-tools-analysis.md`: "Deep statistical analysis of Serena MCP"→"Statistical analysis of Serena MCP" line 2962 (consistency with the title fix). Coverage: 64 spec files (no new files).
 - v9.12 (2026-05-20): Maintenance tone scan — fixed 7 tone issues across 4 spec files: `mods/jsonschema-go.md` (2 fixes: "**Enhanced Type Mapping:** Improved handling of pointer types for nullable fields"→"**Type Mapping:** Improved handling of pointer types for nullable fields" line 119 — "Enhanced" is redundant when the same bullet already says "Improved"; "Enhanced default value support"→"Expanded default value support" line 129 — "Enhanced" is comparative with no baseline, "Expanded" describes the concrete change); `oh-my-code.md` (1 fix: "Provide extensive agent capabilities"→"Provide a broad set of agent capabilities" line 23 — "extensive" is subjective; matches the v6.1 "Comprehensive"→removed pattern); `mcp_logs_guardrails.md` (1 fix: "Runs contain extensive tool usage data"→"Runs contain large volumes of tool usage data" line 9 — replaced subjective "extensive" with concrete "large volumes of"); `github-mcp-access-control-specification.md` (3 fixes: "Only read operations allowed (enhanced security)"→"Only read operations allowed (write operations rejected)" line 407 and "Only triggering repository accessible (enhanced security)"→"Only triggering repository accessible (cross-repo access rejected)" line 508 — "enhanced security" is vague; replaced with the specific behavioral guarantee; "fine-grained permissions, enhanced security posture"→"fine-grained permissions and short-lived tokens" line 2341 — replaced vague "enhanced security posture" with one of the specific properties already listed in the surrounding bullets). Coverage: 64 spec files (no new files).
 - v9.11 (2026-05-19): Maintenance tone scan — fixed 3 tone issues across 3 spec files: `labels.md` (1 fix: "Nice-to-have improvements"→"Lower-priority improvements" line 27; matches the v8.0 "nice to have"→"non-blocking" pattern applied to `agents/hierarchical-agents-quickstart.md`); `serena-tools-analysis.md` (1 fix: "## Serena Tool Usage Deep Dive"→"## Serena Tool Usage Analysis" line 47; matches the v3.8 "Deep analysis"→"Detailed analysis" pattern and v9.7 "deep dive"→"statistical analysis" replacement applied to `serena-tools-quick-reference.md`); `ubuntulatest.md` (1 fix: "cannot be perfectly replicated"→"cannot be fully replicated" line 656; removed redundant intensifier — "perfectly" adds no information when contrasting partial vs. complete replication). Coverage: 64 spec files (no new files).

scratchpad/gastown.md

@@ -941,7 +941,7 @@ Based on patterns from Gastown, here are recommended enhancements for gh-aw:
 - Use Gastown (with beads) for local multi-agent development
 - Bridge with gh-aw workflows that sync with beads state
 - Share formula patterns between systems
-- Leverage GitHub as communication layer for gastown agents
+- Use GitHub as the communication layer for gastown agents
 
 ---
 

scratchpad/github-mcp-access-control-specification.md

@@ -105,7 +105,7 @@ GitHub MCP Server Access Control follows similar integration patterns as Safe In
 - **Configuration Location**: Both extend MCP Gateway server configurations
 - **Validation Timing**: Both validate during workflow compilation
 - **Runtime Enforcement**: Both enforce restrictions at the gateway layer
-- **Schema Extension**: Both leverage MCP Gateway's extensible configuration format
+- **Schema Extension**: Both use MCP Gateway's extensible configuration format
 
 Unlike Safe Inputs (which enables inline tool definition), GitHub MCP Server Access Control restricts access to an existing MCP server (GitHub MCP server) through declarative configuration.
 

scratchpad/mdflow.md

@@ -1352,7 +1352,7 @@ gh aw compile --engine mdflow-compat review.claude.md
 
 **Benefits**:
 - Provide migration path for mdflow users
-- Leverage mdflow's simplicity in gh-aw context
+- Adopt mdflow's minimal-configuration approach in the gh-aw context
 - Enable gradual adoption (start with minimal features, add security later)
 
 ### Final Thoughts

scratchpad/mods/jsonschema-go.md

@@ -50,7 +50,7 @@ func GenerateOutputSchema[T any]() (*jsonschema.Schema, error) {
 }
 ```
 
-**Purpose:** Provides a generic wrapper for schema generation, leveraging Go 1.18+ generics for compile-time type safety.
+**Purpose:** Provides a generic wrapper for schema generation, using Go 1.18+ generics for compile-time type safety.
 
 ### Usage Patterns Observed
 
@@ -144,7 +144,7 @@ While not officially released, upstream development suggests:
    - Could add schema validation for MCP tool inputs/outputs
    - Would provide runtime type safety for AI agent interactions
 
-3. **Leverage Schema Descriptions**
+3. **Use Schema Descriptions**
    - Expand `jsonschema:` tag usage for more detailed tool documentation
    - More detailed descriptions help AI agents understand tool outputs
 

scratchpad/serena-tools-analysis.md

@@ -215,7 +215,7 @@ This pattern suggests:
 - Provide examples of when to use `get_symbols_overview` vs `Read`
 - Highlight benefits of symbol-based navigation over grep/search
 
-### 3. Leverage Unused Capabilities
+### 3. Use Unused Capabilities
 
 **High-Value Unused Tools:**
 - `get_symbols_overview` - Provides structured codebase understanding through symbol hierarchy
@@ -365,7 +365,7 @@ graph LR
 
 The Serena MCP server successfully provided 23 specialized Go language service tools with 100% response rate reliability. However, actual adoption was modest at 20.45% of total tool calls, with only 6 of 23 tools being used. The agent showed a strong preference for general-purpose builtin tools (77.27% usage), particularly Bash and Read operations.
 
-**Key Takeaway:** While Serena tools are reliable and available, the current workflow design doesn't fully leverage their language-aware capabilities. Future optimizations should focus on:
+**Key Takeaway:** While Serena tools are reliable and available, the current workflow design doesn't fully use their language-aware capabilities. Future optimizations should focus on:
 1. Encouraging Serena tool usage through better prompts
 2. Right-sizing tool registration to reduce overhead
 3. Demonstrating value of language-aware operations over text-based alternatives