diff --git a/.github/agents/developer.instructions.md b/.github/agents/developer.instructions.md index 4e31aae9734..9b7d074a289 100644 --- a/.github/agents/developer.instructions.md +++ b/.github/agents/developer.instructions.md @@ -725,4 +725,4 @@ For detailed specifications, see individual files in `scratchpad/`: --- -**Last Updated**: 2026-01-28 +**Last Updated**: 2026-01-30 diff --git a/scratchpad/README.md b/scratchpad/README.md index d7ee6e47b95..3f275103a22 100644 --- a/scratchpad/README.md +++ b/scratchpad/README.md @@ -36,7 +36,7 @@ This directory contains design specifications and implementation documentation f | Document | Status | Description | |----------|--------|-------------| -| [mdflow Syntax Comparison](./mdflow-comparison.md) | ✅ Documented | Comprehensive comparison of mdflow and gh-aw syntax covering 17 aspects: file naming, frontmatter design, templates, imports, security models, execution patterns, and more | +| [mdflow Syntax Comparison](./mdflow-comparison.md) | ✅ Documented | Detailed comparison of mdflow and gh-aw syntax covering 17 aspects: file naming, frontmatter design, templates, imports, security models, execution patterns, and more | | [Gastown Multi-Agent Orchestration](./gastown.md) | ✅ Documented | Deep analysis of Gastown's multi-agent coordination patterns and mapping to gh-aw concepts: persistent state, workflow composition, crash recovery, agent communication, and implementation recommendations | ## Related Documentation diff --git a/scratchpad/actions.md b/scratchpad/actions.md index 40181387856..6fd415ecaa6 100644 --- a/scratchpad/actions.md +++ b/scratchpad/actions.md @@ -61,7 +61,7 @@ Create a custom actions system that: │ internal/tools/actions-build/main.go │ │ (Internal Development Tool) │ │ ┌────────────────────────────────────────────────────┐ │ -│ │ Simple CLI dispatcher for: │ │ +│ │ CLI dispatcher for: │ │ │ │ • build command │ │ │ │ • validate command │ │ │ │ • clean command │ │ @@ -674,7 +674,7 @@ The custom GitHub Actions build system provides a foundation for migrating from ✅ **Makefile integration** for action management ✅ **CI validation** ensuring actions stay buildable ✅ **Setup action** for workflow script management -✅ **Comprehensive documentation** for future development +✅ **Complete documentation** for future development The system is production-ready and extensible, with clear paths for enhancement and migration of existing inline scripts. @@ -1005,7 +1005,7 @@ jobs: - Custom action step generation logic - Token input mapping for custom actions - Backward compatibility (all existing tests pass) -- Comprehensive unit tests +- Unit tests with coverage metrics **⚠️ Known Issues**: - Custom action compilation tests show mode triggers correctly diff --git a/scratchpad/cli-command-patterns.md b/scratchpad/cli-command-patterns.md index 26166af3644..c98b7f27ecb 100644 --- a/scratchpad/cli-command-patterns.md +++ b/scratchpad/cli-command-patterns.md @@ -1,6 +1,6 @@ # CLI Command Patterns and Conventions -This document provides comprehensive guidance for developing CLI commands in GitHub Agentic Workflows. It covers command structure, naming conventions, flag patterns, error handling, testing requirements, and help text standards. +This document provides guidance for developing CLI commands in GitHub Agentic Workflows. It covers command structure, naming conventions, flag patterns, error handling, testing requirements, and help text standards. ## Table of Contents @@ -1073,7 +1073,7 @@ Use this checklist when developing a new command: ## Related Documentation -- **Testing Framework**: See `scratchpad/testing.md` for comprehensive testing guidelines +- **Testing Framework**: See `scratchpad/testing.md` for testing guidelines - **Console Rendering**: See `skills/console-rendering/SKILL.md` for console output details - **Error Messages**: See `skills/error-messages/SKILL.md` for error message style guide - **Code Organization**: See `scratchpad/code-organization.md` for file organization patterns diff --git a/scratchpad/error-recovery-patterns.md b/scratchpad/error-recovery-patterns.md index a02c83fbd4f..dfc97f99e5f 100644 --- a/scratchpad/error-recovery-patterns.md +++ b/scratchpad/error-recovery-patterns.md @@ -1,6 +1,6 @@ # Error Recovery Patterns -This document provides comprehensive guidance for error handling, common error scenarios, recovery strategies, and debugging techniques in GitHub Agentic Workflows (gh-aw). +This document provides guidance for error handling, common error scenarios, recovery strategies, and debugging techniques in GitHub Agentic Workflows (gh-aw). ## Table of Contents @@ -116,7 +116,7 @@ func compileWorkflow(file string) error { Internal error types (like `yaml.TypeError`, `os.PathError`) are implementation details that should not leak to user-facing error messages. Breaking the chain with `errors.New()` or `fmt.Errorf()` (without `%w`) prevents downstream code from making assumptions about internal error types. -See `pkg/workflow/error_wrapping_test.go` for comprehensive examples of error wrapping patterns. +See `pkg/workflow/error_wrapping_test.go` for examples of error wrapping patterns. **Key rules:** - Use `%w` for internal errors that need type checking @@ -1128,7 +1128,7 @@ return fmt.Errorf( - Explain what's expected (format, valid values, type) - Provide concrete example of correct usage -See `skills/error-messages/SKILL.md` for comprehensive style guide. +See `skills/error-messages/SKILL.md` for the style guide. ### Runtime Error Template @@ -1616,7 +1616,7 @@ graph TD ### Related Documentation -- **[Error Message Style Guide](../skills/error-messages/SKILL.md)** - Comprehensive guide for writing validation error messages +- **[Error Message Style Guide](../skills/error-messages/SKILL.md)** - Guide for writing validation error messages - **[Console Formatting](../AGENTS.md#console-message-formatting)** - Console formatting requirements and helpers - **[Debug Logging](../pkg/logger/README.md)** - Logger package documentation with DEBUG environment variable syntax - **[Validation Architecture](validation-architecture.md)** - Overview of validation system organization diff --git a/scratchpad/gosec.md b/scratchpad/gosec.md index 075e67997b7..bc07dfcf7c1 100644 --- a/scratchpad/gosec.md +++ b/scratchpad/gosec.md @@ -5,7 +5,7 @@ applyTo: "**/*" # Gosec Security Exclusions -This document provides comprehensive documentation for all gosec security rule exclusions configured in `.golangci.yml`. These exclusions have been reviewed for security impact and provide an audit trail for compliance requirements. +This document provides documentation for all gosec security rule exclusions configured in `.golangci.yml`. These exclusions have been reviewed for security impact and provide an audit trail for compliance requirements. ## Configuration Source diff --git a/scratchpad/mdflow.md b/scratchpad/mdflow.md index 5e4a56517a0..13854934027 100644 --- a/scratchpad/mdflow.md +++ b/scratchpad/mdflow.md @@ -8,7 +8,7 @@ ## Executive Summary -This document provides a deep technical analysis of mdflow and GitHub Agentic Workflows (gh-aw), focusing on custom engine opportunities, architectural patterns, and strategic insights for gh-aw development. While the existing `mdflow-comparison.md` provides a comprehensive syntax comparison, this document focuses on **what gh-aw can learn from mdflow** and **opportunities for custom engine development**. +This document provides a deep technical analysis of mdflow and GitHub Agentic Workflows (gh-aw), focusing on custom engine opportunities, architectural patterns, and strategic insights for gh-aw development. While the existing `mdflow-comparison.md` provides a detailed syntax comparison, this document focuses on **what gh-aw can learn from mdflow** and **opportunities for custom engine development**. ### Key Findings @@ -693,13 +693,13 @@ mdflow compile task.claude.md --output github-actions.yml #### 1. **Simplified Quickstart Templates** - Create `gh aw init` with curated templates -- mdflow-inspired simple syntax option +- mdflow-inspired minimal syntax option - Reduce boilerplate for common use cases **Example**: ```bash gh aw init issue-responder -gh aw init pr-reviewer --simple +gh aw init pr-reviewer --basic gh aw init daily-report --template mdflow ``` @@ -1156,7 +1156,7 @@ CI/CD Execution (gh-aw): **Size**: Enterprise-focused, GitHub-backed - GitHub stars: Growing (GitHub Next project) - Contributors: Microsoft Research + community -- Examples: Comprehensive documentation site +- Examples: Full documentation site **Integration**: - GitHub Actions ecosystem @@ -1173,7 +1173,7 @@ CI/CD Execution (gh-aw): **Documentation**: - Full documentation site (Astro Starlight) - Video tutorials and slides -- Comprehensive specifications (scratchpad/ directory) +- Detailed specifications (scratchpad/ directory) - Enterprise security guidelines --- @@ -1310,7 +1310,7 @@ CI/CD Execution (gh-aw): ### Key Takeaways -1. **mdflow excels at**: Personal productivity, local tasks, simple workflows, fast iteration +1. **mdflow excels at**: Personal productivity, local tasks, basic workflows, fast iteration 2. **gh-aw excels at**: Team automation, CI/CD, security, GitHub integration, structured output 3. **They serve different needs**: mdflow = developer tool, gh-aw = platform tool 4. **Cross-pollination is valuable**: Each can learn from the other's strengths @@ -1318,7 +1318,7 @@ CI/CD Execution (gh-aw): ### Top 3 Recommendations for gh-aw #### 1. **Simplified Quickstart Experience** (Inspired by mdflow) -- Create "simple mode" templates that hide complexity +- Create "basic mode" templates that hide complexity - Add `gh aw init --template mdflow-style` for familiar syntax - Provide sensible defaults that work out-of-the-box @@ -1354,7 +1354,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 -- Enable gradual adoption (start simple, add security later) +- Enable gradual adoption (start with minimal features, add security later) ### Final Thoughts diff --git a/scratchpad/oh-my-code.md b/scratchpad/oh-my-code.md index 7da0e64ab50..63143e27b0f 100644 --- a/scratchpad/oh-my-code.md +++ b/scratchpad/oh-my-code.md @@ -20,7 +20,7 @@ This document provides a deep research comparison between **oh-my-opencode** and | **Multi-Agent** | Native multi-agent orchestration | Single-agent per workflow (event-driven) | | **Tool Ecosystem** | LSP, AST-Grep, MCP servers | GitHub MCP, Bash allowlist, Playwright | | **State Management** | Stateful, persistent across sessions | Stateless workflow runs | -| **Philosophy** | Provide comprehensive agent capabilities | "Safe by default" - minimize risk | +| **Philosophy** | Provide extensive agent capabilities | "Safe by default" - minimize risk | --- @@ -1077,7 +1077,7 @@ gh aw mcp inspect issue-responder **Scalability**: - **Horizontal**: Unlimited parallel workflows (GitHub manages) -- **Vertical**: Use more powerful runners (self-hosted or GitHub) +- **Vertical**: Use higher-spec runners (self-hosted or GitHub) - **Cost**: Pay for Actions minutes + LLM tokens **Optimization Tips**: @@ -1449,7 +1449,7 @@ Use oh-my-opencode with gh-aw integration: **Ideal User Profiles**: - **Power Users**: Developers who want "coding on steroids" - **Refactoring Projects**: Large-scale code transformations -- **Rapid Prototyping**: Build features quickly with parallel agents +- **Rapid Prototyping**: Build features using parallel agents - **Open Source Contributors**: Personal productivity tool - **Consultants**: Accelerate client projects @@ -1585,7 +1585,7 @@ Merge and Deploy: 4. **Simplified Configuration** - Add "auto" mode that detects needed tools - Implement preset configurations for common workflows - - Reduce boilerplate for simple cases + - Reduce boilerplate for basic use cases ### 15.2 Potential oh-my-opencode Enhancements Inspired by gh-aw diff --git a/scratchpad/schema-validation.md b/scratchpad/schema-validation.md index da80525e657..e3b179ef28e 100644 --- a/scratchpad/schema-validation.md +++ b/scratchpad/schema-validation.md @@ -30,7 +30,7 @@ When `"additionalProperties": false` is set at the root level of a JSON schema, ## Testing -Comprehensive test coverage is provided in: +Test coverage is provided in: - **File**: `pkg/parser/schema_additional_properties_test.go` - **Test cases**: Tests for common typos and validation - Tests for common typos in main workflow schema diff --git a/scratchpad/styles-guide.md b/scratchpad/styles-guide.md index dfa734ae0f4..1fc9c81c923 100644 --- a/scratchpad/styles-guide.md +++ b/scratchpad/styles-guide.md @@ -5,7 +5,7 @@ ## Overview -This document provides a comprehensive visual guide to the adaptive color palette and styling system used in GitHub Agentic Workflows. The system uses [lipgloss](https://github.com/charmbracelet/lipgloss) with adaptive colors that automatically adjust based on the user's terminal theme (light or dark). +This document provides a complete visual guide to the adaptive color palette and styling system used in GitHub Agentic Workflows. The system uses [lipgloss](https://github.com/charmbracelet/lipgloss) with adaptive colors that automatically adjust based on the user's terminal theme (light or dark). **Implementation**: `pkg/styles/theme.go` @@ -13,7 +13,7 @@ This document provides a comprehensive visual guide to the adaptive color palett ### Adaptive Color Strategy -GitHub Agentic Workflows uses an adaptive color system that provides optimal readability in both light and dark terminals: +GitHub Agentic Workflows uses an adaptive color system that provides readability in both light and dark terminals: **Light Mode**: - Darker, more saturated colors for visibility on light backgrounds @@ -226,7 +226,7 @@ When adding new styles to the system: - Include visual examples - Document semantic usage -### Best Practices +### Recommended Practices **DO**: - ✅ Use semantic colors consistently across the codebase @@ -290,7 +290,7 @@ When developing new features that use colors: ### Testing -The color system includes comprehensive tests: +The color system includes tests: - `TestAdaptiveColorsHaveBothVariants` - Ensures all colors have light and dark variants - `TestColorFormats` - Validates hex color format - `TestDarkColorsAreOriginalDracula` - Ensures dark mode maintains Dracula theme colors diff --git a/scratchpad/testing.md b/scratchpad/testing.md index f23f7349a07..a0fb3b96708 100644 --- a/scratchpad/testing.md +++ b/scratchpad/testing.md @@ -1,10 +1,10 @@ # Testing Guidelines and Framework -This document covers testing patterns, conventions, and the comprehensive testing framework for GitHub Agentic Workflows. +This document covers testing patterns, conventions, and the testing framework for GitHub Agentic Workflows. ## Testing Guidelines for Contributors -GitHub Agentic Workflows has comprehensive testing practices (699 test files, 1,061+ table-driven tests). Understanding these patterns helps maintain code quality and consistency. +GitHub Agentic Workflows has extensive testing practices (699 test files, 1,061+ table-driven tests). Understanding these patterns helps maintain code quality and consistency. ### Test Organization @@ -155,7 +155,7 @@ This project **intentionally avoids** mocking frameworks and test suites: - **Confidence**: Tests catch real integration issues **No test suites (testify/suite) because:** -- **Parallel execution**: Standard Go tests run in parallel efficiently +- **Parallel execution**: Standard Go tests run in parallel by default - **Simplicity**: No suite lifecycle methods to understand - **Explicitness**: Setup is visible in each test - **Compatibility**: Compatible with standard `go test` tooling @@ -207,13 +207,13 @@ make agent-finish # Runs build, test, recompile, fmt, lint --- -## Comprehensive Testing Framework +## Testing Framework -This section describes the comprehensive testing framework added to ensure the Go implementation of gh-aw matches the bash version exactly and maintains high quality standards. +This section describes the testing framework added to ensure the Go implementation of gh-aw matches the bash version exactly and maintains high quality standards. ### Overview -The testing framework implements **Phase 6 (Quality Assurance)** of the Go reimplementation project, providing comprehensive validation that the Go implementation behaves identically to the bash version while maintaining code quality and reliability. +The testing framework implements **Phase 6 (Quality Assurance)** of the Go reimplementation project, providing validation that the Go implementation behaves identically to the bash version while maintaining code quality and reliability. ### Testing Structure @@ -371,7 +371,7 @@ benchstat bench_baseline.txt bench_new.txt ### 5. Test Validation Framework (`test_validation.go`) -Comprehensive validation system that ensures: +Validation system that ensures: #### Unit Test Validation - All package tests pass @@ -404,7 +404,7 @@ go test ./pkg/... -v # Run security regression tests make test-security -# Run comprehensive validation +# Run validation go run test_validation.go ```text @@ -441,7 +441,7 @@ Security tests are integrated into: ### Current Implementation Status The tests are designed to work with the current implementation state: -- **Completed functionality**: Fully tested with comprehensive coverage +- **Completed functionality**: Tested with high coverage - **Stub implementations**: Interface stability testing to ensure future compatibility - **Missing functionality**: Framework prepared for when implementation is complete @@ -479,7 +479,7 @@ This testing framework ensures: 1. **Regression Prevention**: Any changes that break existing functionality will be caught 2. **Interface Stability**: CLI and API interfaces remain consistent 3. **Behavioral Compatibility**: Go implementation will match bash behavior exactly -4. **Code Quality**: High test coverage and comprehensive validation +4. **Code Quality**: High test coverage and validation 5. **Future Readiness**: Testing infrastructure scales with implementation progress 6. **Security Assurance**: Security fixes remain effective over time @@ -487,11 +487,11 @@ This testing framework ensures: The testing framework is designed to be: - **Self-validating**: The validation script ensures all tests work correctly -- **Comprehensive**: Covers all aspects of functionality and interface design +- **Complete**: Covers all aspects of functionality and interface design - **Maintainable**: Clear structure and documentation for future updates - **Scalable**: Tests can be added incrementally as functionality is implemented - **Security-focused**: Security regression tests prevent reintroduction of vulnerabilities ## Conclusion -This comprehensive testing framework provides a solid foundation for ensuring the Go implementation of gh-aw maintains compatibility with the bash version while providing high-quality, reliable, and secure functionality. The framework is immediately useful for current development and ready to scale as implementation progresses. \ No newline at end of file +This testing framework provides a solid foundation for ensuring the Go implementation of gh-aw maintains compatibility with the bash version while providing high-quality, reliable, and secure functionality. The framework is immediately useful for current development and ready to scale as implementation progresses. \ No newline at end of file diff --git a/scratchpad/token-budget-guidelines.md b/scratchpad/token-budget-guidelines.md index 5def1966693..b20dc0971b4 100644 --- a/scratchpad/token-budget-guidelines.md +++ b/scratchpad/token-budget-guidelines.md @@ -85,7 +85,7 @@ Explicit instructions in workflow prompts to reduce token consumption: - Test 6-8 representative scenarios (not all scenarios) - Focus on quality over quantity -- Prioritize critical issues over comprehensive coverage +- Prioritize critical issues over complete coverage ``` **Efficiency Instructions:** @@ -108,7 +108,7 @@ Explicit instructions in workflow prompts to reduce token consumption: - No token budget controls - 600-minute timeout - Tests all 15-20 generated scenarios -- Comprehensive documentation +- Complete documentation **Optimized Configuration:** - `timeout-minutes: 180` (reduced from 600) @@ -130,7 +130,7 @@ Explicit instructions in workflow prompts to reduce token consumption: - Reduce test scenarios from 15-20 to 6-8 representative cases - Enforce concise output with word limits - Use progressive disclosure to hide verbose content -- Focus on quality insights over comprehensive coverage +- Focus on quality insights over complete coverage ### CI Cleaner @@ -184,7 +184,7 @@ Test a representative subset of 6-8 scenarios to reduce token consumption... **Before:** ```markdown ### Detailed Analysis -[5000 word comprehensive report with all scenario details] +[5000 word detailed report with all scenario details] ``` **After:** diff --git a/scratchpad/validation-architecture.md b/scratchpad/validation-architecture.md index 85a4138e8a5..0e2e369a9bb 100644 --- a/scratchpad/validation-architecture.md +++ b/scratchpad/validation-architecture.md @@ -110,7 +110,7 @@ Domain-specific validation is organized into separate files based on functional - `validateExpressionSafety()` - Validates allowed GitHub expressions - `validateSingleExpression()` - Validates individual expression syntax -**Pattern**: Security-focused allowlist validation with comprehensive error reporting +**Pattern**: Security-focused allowlist validation with detailed error reporting **When to add validation here**: - ✅ GitHub Actions expression parsing