githubnext · pelikhan · Jan 30, 2026 · Jan 30, 2026
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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,15 +1310,15 @@ 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
 
 ### 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
@@ -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
@@ -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
@@ -5,15 +5,15 @@
 
 ## 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`
 
 ## Design Philosophy
 
 ### 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
@@ -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,19 +479,19 @@ 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
 
 ## Test Maintenance
 
 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.
+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.
diff --git 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
@@ -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
Original file line number	Diff line number	Diff line change
Expand Up		@@ -725,4 +725,4 @@ For detailed specifications, see individual files in `scratchpad/`:

		---

		Last Updated: 2026-01-28
		Last Updated: 2026-01-30