diff --git a/.github/agents/developer.instructions.md b/.github/agents/developer.instructions.md index 9b7d074a289..3f66e7a3f5c 100644 --- 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 index 3f275103a22..e8c1ac18b52 100644 --- 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 index e4be5632d6b..e78e9efe245 100644 --- 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 index 4b36fccf16a..6ab4f757729 100644 --- 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 index c98b7f27ecb..ce0e47e4203 100644 --- 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 index b9f592d071f..c068e89642d 100644 --- 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 index 9bea2247c61..f73d068f694 100644 --- 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 index dfc97f99e5f..41d0a73bfd2 100644 --- 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 index 374464c1554..291bb95c0ad 100644 --- 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 index a249469eb18..a513ba44ae1 100644 --- 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 index 72d2357ff8a..286ba909501 100644 --- 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 index 9673824c941..8ff1d311b41 100644 --- 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 index 436660a8ffd..012ef8f11e2 100644 --- 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 index 038bc3b8413..1dcfe1a7896 100644 --- 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 index 13854934027..801f778ef49 100644 --- 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 { 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 index c3f06cef0a5..8cdc0068fdf 100644 --- 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 index 63143e27b0f..02cc6232dea 100644 --- 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 index f4f8bc7d7da..a86f6a92a11 100644 --- 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 index b20dc0971b4..0d17414b6b3 100644 --- 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 index 74cb43d0097..2b4ad6f7a88 100644 --- 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)