github · pelikhan · Jan 31, 2026 · Jan 31, 2026
diff --git a/.github/agents/developer.instructions.md b/.github/agents/developer.instructions.md
@@ -5,7 +5,7 @@ applyTo: "**/*"
 
 # Developer Instructions
 
-This document consolidates development guidelines, architectural patterns, and implementation standards for GitHub Agentic Workflows. It provides comprehensive guidance for contributing to the codebase while maintaining consistency, security, and code quality.
+This document consolidates development guidelines, architectural patterns, and implementation standards for GitHub Agentic Workflows. It provides guidance for contributing to the codebase while maintaining consistency, security, and code quality.
 
 ## Table of Contents
 
@@ -725,4 +725,4 @@ For detailed specifications, see individual files in `scratchpad/`:
 
 ---
 
-**Last Updated**: 2026-01-30
+**Last Updated**: 2026-01-31
diff --git a/scratchpad/README.md b/scratchpad/README.md
@@ -48,7 +48,7 @@ For user-facing documentation, see [docs/](../docs/).
 When adding new specifications:
 
 1. Document implementation details with file paths
-2. Mark status clearly: ✅ Implemented, 🚧 In Progress, or 📋 Planned
+2. Mark status with standard icons: ✅ Implemented, 🚧 In Progress, or 📋 Planned
 3. Provide code samples and usage patterns
 4. Link to test files
 5. Update this README's table

diff --git a/scratchpad/agent-container-testing.md b/scratchpad/agent-container-testing.md
@@ -138,7 +138,7 @@ java --version
 dotnet --version
 ```
 
-Or run a comprehensive check:
+Or run validation checks for all required tools:
 
 ```bash
 for tool in bash git jq yq curl gh node python3 go java dotnet; do

diff --git a/scratchpad/breaking-cli-rules.md b/scratchpad/breaking-cli-rules.md
@@ -178,7 +178,7 @@ The following changes are **not breaking** and typically require:
 ### When Making CLI Changes
 
 1. **Check the decision tree** before implementing changes
-2. **Document breaking changes** clearly in the changeset
+2. **Document breaking changes** in the changeset with deprecation notice, migration path, and timeline
 3. **Provide migration guidance** for users affected by breaking changes
 4. **Consider backward compatibility** - can you add an alias instead of renaming?
 5. **Use deprecation warnings** for at least one minor release before removal

diff --git a/scratchpad/cli-command-patterns.md b/scratchpad/cli-command-patterns.md
@@ -252,7 +252,7 @@ Reserve these short flags for consistent meanings:
 ### Flag Naming
 
 - Use **kebab-case** for flag names: `--output-dir`, `--run-id`
-- Use descriptive names that clearly indicate purpose
+- Use descriptive names that indicate purpose with noun phrases and conventional prefixes
 - Avoid abbreviations unless universally understood
 
 ### Flag Validation

diff --git a/scratchpad/code-organization.md b/scratchpad/code-organization.md
@@ -101,7 +101,7 @@ The codebase exhibits several well-organized patterns that should be emulated:
 **Why it works**:
 - Tests are co-located with implementation
 - Clear test purpose from filename
-- Encourages comprehensive testing
+- Supports test coverage requirements
 - Separates integration from unit tests
 
 ## File Organization Principles
@@ -214,7 +214,7 @@ The following files are justified despite their size due to domain complexity:
 ### Recommended Sizes
 
 - **Small files**: 50-200 lines
-  - Utilities, simple features, helpers
+  - Utilities, single-purpose functions, helper methods
   - Examples: `args.go` (65 lines), `artifacts.go` (60 lines)
 
 - **Medium files**: 200-500 lines

diff --git a/scratchpad/end-to-end-feature-testing.md b/scratchpad/end-to-end-feature-testing.md
@@ -189,7 +189,7 @@ Create multiple instances of the new output type to verify rate limiting and tar
 
 ### For Repository Hygiene
 
-1. **Don't merge dev.md changes**: The dev.md file should remain a simple, reusable test harness
+1. **Don't merge dev.md changes**: The dev.md file should remain a minimal test harness with no feature-specific logic
 2. **Reset dev.md after testing**: Restore it to the default configuration
 3. **Focus PR changes on the actual feature**: Keep test changes separate from feature implementation
 

diff --git a/scratchpad/error-recovery-patterns.md b/scratchpad/error-recovery-patterns.md
@@ -49,7 +49,7 @@ fmt.Fprintf(os.Stderr, "Error: %v\n", err)
 - **ALWAYS** use `fmt.Fprintln(os.Stderr, ...)` or `fmt.Fprintf(os.Stderr, ...)` for CLI logging
 - **NEVER** use `fmt.Println()` or `fmt.Printf()` directly - all output should go to stderr
 - Use console formatting helpers with `os.Stderr` for consistent styling
-- For simple messages without console formatting: `fmt.Fprintf(os.Stderr, "message\n")`
+- For plain text messages without ANSI formatting: `fmt.Fprintf(os.Stderr, "message\n")`
 - **Exception**: JSON output goes to stdout, all other output to stderr
 
 **Available console formatters:**

diff --git a/scratchpad/firewall-log-parsing.md b/scratchpad/firewall-log-parsing.md
@@ -276,7 +276,7 @@ This implementation successfully adds a complete Golang firewall logs parser tha
 - ✓ Mirrors the JavaScript parser field-by-field
 - ✓ Integrates into logs and audit commands
 - ✓ Provides console and JSON output
-- ✓ Includes comprehensive tests
+- ✓ Includes tests covering all parsing scenarios
 - ✓ Maintains backward compatibility
 - ✓ Follows project standards
 - ✓ Is fully documented
diff --git a/scratchpad/gastown.md b/scratchpad/gastown.md
@@ -7,7 +7,7 @@
 
 ## Executive Summary
 
-This document maps concepts from Steve Yegge's **Gastown** multi-agent orchestrator to **GitHub Agentic Workflows** (gh-aw). Gastown provides a robust system for managing multiple AI coding agents with persistent state, structured handoffs, and crash recovery. While the two systems have different architectural approaches, understanding Gastown's patterns can inform gh-aw's evolution toward multi-agent coordination, persistent state management, and workflow composition.
+This document maps concepts from Steve Yegge's **Gastown** multi-agent orchestrator to **GitHub Agentic Workflows** (gh-aw). Gastown provides a multi-agent orchestration system with persistent state management, structured handoffs, and crash recovery mechanisms. While the two systems have different architectural approaches, understanding Gastown's patterns can inform gh-aw's evolution toward multi-agent coordination, persistent state management, and workflow composition.
 
 ### Key Insight
 

diff --git a/scratchpad/github-actions-security-best-practices.md b/scratchpad/github-actions-security-best-practices.md
@@ -914,7 +914,7 @@ jobs:
 ### Audit Logging
 
 ```yaml
-# Enable comprehensive logging
+# Enable structured audit logging
 steps:
   - name: Audit action
     run: |

diff --git a/scratchpad/go-type-patterns.md b/scratchpad/go-type-patterns.md
@@ -661,7 +661,7 @@ type ToolConfig interface {
 - Only one implementation exists and no others are planned
 - The data structure itself is the interface (use structs)
 - It adds indirection without benefit
-- A simple function would suffice
+- A single-purpose function returning one type would suffice
 
 ### Interface Best Practices
 

diff --git a/scratchpad/mcp_logs_guardrails.md b/scratchpad/mcp_logs_guardrails.md
@@ -4,7 +4,7 @@ This document describes the output size guardrail implemented for the MCP server
 
 ## Problem
 
-When using the MCP server to fetch workflow logs, the output can become very large, especially when:
+When using the MCP server to fetch workflow logs, the output can exceed GitHub's API limits, especially when:
 - Fetching logs for many workflow runs
 - Runs contain extensive tool usage data
 - Multiple workflows are being analyzed

diff --git a/scratchpad/mdflow-comparison.md b/scratchpad/mdflow-comparison.md
@@ -6,7 +6,7 @@
 
 ## Executive Summary
 
-This document provides a comprehensive comparison between mdflow's syntax and GitHub Agentic Workflows (gh-aw) syntax. Both projects enable AI-driven automation through markdown files, but they target different use cases and have different design philosophies.
+This document provides a detailed syntax comparison between mdflow and GitHub Agentic Workflows (gh-aw). Both projects enable AI-driven automation through markdown files, but they target different use cases and have different design philosophies.
 
 ### Key Differences at a Glance
 

diff --git a/scratchpad/mdflow.md b/scratchpad/mdflow.md
@@ -203,7 +203,7 @@ Interactive debugging session for issue #${{ inputs.issue_number }}
 
 **Lesson for gh-aw**: Provide "Quick Start" templates that abstract complexity:
 ```bash
-gh aw init simple-issue-responder
+gh aw init basic-issue-responder
 # Generates pre-configured workflow with sensible defaults
 ```
 
@@ -720,7 +720,7 @@ gh aw init daily-report --template mdflow
 #### 4. **Better Error Messages**
 - Learn from mdflow's simplicity
 - Show "did you mean?" suggestions
-- Explain validation failures clearly
+- Explain validation failures with specific error codes and context
 
 **Example**:
 ```
@@ -1113,14 +1113,14 @@ class LRUCache<K, V> {
 Local Execution (mdflow):
   Cold start:    50-100ms
   Warm start:    10-20ms
-  Total (simple): ~1 second
-  
+  Total (minimal config): ~1 second
+
 CI/CD Execution (gh-aw):
   Compilation:   1-2 seconds
   Queue time:    0-60 seconds
   Cold start:    10-30 seconds
   Execution:     30-300 seconds
-  Total (simple): ~1-5 minutes
+  Total (minimal config): ~1-5 minutes
 ```
 
 ---
@@ -1462,7 +1462,7 @@ func TestImportParsing(t *testing.T) {
         expected []string
     }{
         {
-            name:     "simple import",
+            name:     "single_file_import",
             input:    "imports: [file1.md]",
             expected: []string{"file1.md"},
         },

diff --git a/scratchpad/mods/jsonschema-go.md b/scratchpad/mods/jsonschema-go.md
@@ -2,7 +2,7 @@
 
 ## Overview
 
-**jsonschema-go** is Google's official Go library for working with JSON Schema, providing comprehensive support for schema creation, validation, and type inference. The library fully implements the JSON Schema Draft 2020-12 specification with no external dependencies beyond the Go standard library.
+**jsonschema-go** is Google's official Go library for working with JSON Schema, supporting schema creation, validation, and type inference per JSON Schema Draft 2020-12 specification. The library fully implements the JSON Schema Draft 2020-12 specification with no external dependencies beyond the Go standard library.
 
 **Key Characteristics:**
 - Zero external dependencies (only Go stdlib)
@@ -187,7 +187,7 @@ While not officially released, upstream development suggests:
 
 4. **Testing Coverage**
    - ✅ Comprehensive test coverage for schema generation
-   - ✅ Tests for simple, nested, and array types
+   - ✅ Tests for scalar types, nested objects, and array elements
    - 💡 Could add validation tests for schema correctness
 
 ### General Code Improvements
@@ -243,7 +243,7 @@ tool := &mcp.Tool{
    - Consider `*string` vs `string` based on nullability needs
 
 3. **Avoid Complex Types When Possible**
-   - Prefer simple Go types that map clearly to JSON Schema
+   - Use built-in Go types with direct JSON Schema mappings
    - Use structs for complex objects rather than maps
    - Document any custom type mappings
 

diff --git a/scratchpad/oh-my-code.md b/scratchpad/oh-my-code.md
@@ -177,7 +177,7 @@ Use GitHub MCP to access PR files and repository context.
 **Key Benefits**:
 - Runs automatically on GitHub events
 - Sandboxed, secure execution
-- Team-wide automation (not just one developer)
+- Supports multi-user repository automation
 - Audit trail via GitHub Actions logs
 - Integration with Issues, PRs, Discussions
 
@@ -945,7 +945,7 @@ User: "ultrawork - Refactor authentication to use OAuth2"
 - Explore: Finds similar OAuth patterns in codebase
 - Todo Enforcer: Ensures all subtasks complete
 
-# Output: Production-ready code, comprehensive tests, documentation
+# Output: Code passing validation, tests meeting coverage targets, documentation generated
 ```
 
 **Key Features**:
@@ -1458,7 +1458,7 @@ Use oh-my-opencode with gh-aw integration:
 - "Implement authentication system with UI and backend"
 - "Debug complex race condition with Oracle agent"
 - "Migrate codebase from JavaScript to TypeScript"
-- "Add comprehensive tests across entire project"
+- "Implement test coverage meeting 80%+ threshold across all modules"
 
 ### 13.2 When to Choose GitHub Agentic Workflows
 
@@ -1643,7 +1643,7 @@ oh-my-opencode and GitHub Agentic Workflows represent two complementary approach
 - Use **oh-my-opencode** when you need full-featured local development with AI agents as teammates
 - Use **gh-aw** when you need secure, auditable automation for team/org workflows
 
-**Together, they provide a comprehensive AI-powered development stack**:
+**Together, they provide an integrated AI development automation stack**:
 - Rapid local development (oh-my-opencode)
 - Safe CI/CD automation (gh-aw)
 - Clear separation of concerns

diff --git a/scratchpad/safe-output-messages.md b/scratchpad/safe-output-messages.md
@@ -833,7 +833,7 @@ Related to #123
 ## Design Patterns
 
 ### Consistent Footer Format
-All AI-generated content uses a blockquote footer format to clearly identify the source:
+All AI-generated content uses a blockquote footer format to identify the source via standard formatting:
 - Basic: `> AI generated by [WorkflowName](run_url)`
 - With context: `> AI generated by [WorkflowName](run_url) for #123`
 

diff --git a/scratchpad/token-budget-guidelines.md b/scratchpad/token-budget-guidelines.md
@@ -59,7 +59,7 @@ Prevents workflows from running indefinitely due to unexpected loops or delays.
 ---
 timeout-minutes: 180  # 3 hours - research workflows
 timeout-minutes: 45   # 45 minutes - CI cleanup workflows
-timeout-minutes: 20   # 20 minutes - simple automation
+timeout-minutes: 20   # 20 minutes - single-step automation
 ---
 ```
 

diff --git a/scratchpad/ubuntulatest.md b/scratchpad/ubuntulatest.md
@@ -10,7 +10,7 @@
 
 ## Overview
 
-This document provides an analysis of the default GitHub Actions Ubuntu runner image (`ubuntu-latest`, currently Ubuntu 24.04) and guidance for creating Docker images that mimic its environment. The runner image is a comprehensive development environment with pre-installed tools, runtimes, databases, and build systems commonly used in CI/CD pipelines.
+This document provides an analysis of the default GitHub Actions Ubuntu runner image (`ubuntu-latest`, currently Ubuntu 24.04) and guidance for creating Docker images that mimic its environment. The runner image is a development environment with 200+ pre-installed tools including runtimes, databases, and build systems commonly used in CI/CD pipelines.
 
 **Key Features**:
 - Multiple language runtimes (Node.js, Python, Ruby, Go, Java, PHP, Rust)