diff --git a/scratchpad/actions.md b/scratchpad/actions.md index 00c72d6724c..7bc3e7777f5 100644 --- a/scratchpad/actions.md +++ b/scratchpad/actions.md @@ -676,7 +676,7 @@ The custom GitHub Actions build system provides a foundation for migrating from ✅ **Setup action** for workflow script management ✅ **Complete documentation** for future development -The system is production-ready and extensible, with clear paths for enhancement and migration of existing inline scripts. +The system supports enhancement and migration of existing inline scripts via the extension points documented above. ## Compiler Integration: Action Modes diff --git a/scratchpad/code-organization.md b/scratchpad/code-organization.md index 8ab3da08aac..e5435f66ab0 100644 --- a/scratchpad/code-organization.md +++ b/scratchpad/code-organization.md @@ -14,7 +14,7 @@ This document provides guidance on file organization patterns and best practices ## Recommended Patterns to Follow -The codebase exhibits several well-organized patterns that should be emulated: +The codebase follows several consistent patterns that should be emulated: ### 1. Create Functions Pattern (`create_*.go`) diff --git a/scratchpad/dev.md b/scratchpad/dev.md index 07e8f297142..aca9e67d9f5 100644 --- a/scratchpad/dev.md +++ b/scratchpad/dev.md @@ -1,7 +1,7 @@ # Developer Instructions -**Version**: 2.5 -**Last Updated**: 2026-02-19 +**Version**: 2.6 +**Last Updated**: 2026-02-20 **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. @@ -224,6 +224,12 @@ This is a guideline, not a hard rule. Domain complexity may justify larger files - `scripts.go` (37 functions, 397 lines) - Script generation with specialized functions - `compiler_safe_outputs_consolidated.go` (30 functions, 1267 lines) - Consolidated safe output handling +**Post-Processing Extraction Pattern**: + +When a compilation command accumulates unrelated post-processing steps, extract them into a dedicated `*_post_processing.go` file. Example: `pkg/cli/compile_post_processing.go` groups Dependabot manifest generation, maintenance workflow generation, and `.gitattributes` updates — all operations that run after workflow compilation completes. + +Key rule: wrapper functions in post-processing files must propagate all relevant CLI flags (e.g., `actionTag`, `version`) to the underlying generators. Missing parameter propagation causes flags to be silently ignored in specific execution modes. + ### Anti-Patterns to Avoid **❌ God Files** @@ -1776,6 +1782,7 @@ type Everything interface { --- **Document History**: +- v2.6 (2026-02-20): Fixed 8 tone issues across 4 spec files, documented post-processing extraction pattern and CLI flag propagation rule from PR #17316, analyzed 61 files - v2.5 (2026-02-19): Fixed 6 tone issues in engine review docs, added Engine-Specific MCP Config Delivery section (Gemini pattern), analyzed 61 files - v2.4 (2026-02-17): Quality verification - analyzed 4 new files, zero tone issues found across all 61 files - v2.3 (2026-02-16): Quality verification - zero tone issues, all formatting standards maintained diff --git a/scratchpad/engine-architecture-review.md b/scratchpad/engine-architecture-review.md index f1d35482831..2af70609a88 100644 --- a/scratchpad/engine-architecture-review.md +++ b/scratchpad/engine-architecture-review.md @@ -37,7 +37,7 @@ CodingAgentEngine (composite) └── SecurityProvider (security features) ``` -**Assessment**: ✅ **Excellent**. This design follows SOLID principles and allows engines to implement only what they need via BaseEngine embedding. +**Assessment**: ✅ This design follows SOLID principles and allows engines to implement only what they need via BaseEngine embedding. ### Current Implementations @@ -48,7 +48,7 @@ CodingAgentEngine (composite) | Codex | Production | Medium | TOML config, firewall, LLM gateway | | Custom | Production | Low | User-defined steps, minimal features | -**Assessment**: ✅ **Good variety**. Implementations range from simple (Custom) to complex (Copilot), providing good examples for new engine authors. +**Assessment**: ✅ Implementations range from simple (Custom) to complex (Copilot), providing reference examples for new engine authors. ### Registry & Validation @@ -58,7 +58,7 @@ The engine registry (`EngineRegistry`) provides: - Validation of engine IDs - Plugin support validation -**Assessment**: ✅ **Well-designed**. The registry pattern allows dynamic engine discovery and validation. +**Assessment**: ✅ The registry pattern allows dynamic engine discovery and validation. ### Shared Utilities @@ -69,7 +69,7 @@ Key helper functions in `engine_helpers.go`: - `BuildAWFCommand()` - firewall integration - `FilterEnvForSecrets()` - security filtering -**Assessment**: ✅ **Excellent**. Shared utilities reduce code duplication and ensure consistency. +**Assessment**: ✅ Shared utilities reduce code duplication and ensure consistency. ## Implementation Review @@ -78,7 +78,7 @@ Key helper functions in `engine_helpers.go`: **Files**: 7 modular files (copilot_engine.go, copilot_engine_installation.go, etc.) **Strengths**: -- ✅ Excellent modular organization +- ✅ Modular organization (7 files) - ✅ Comprehensive MCP support - ✅ Full firewall integration - ✅ Plugin support @@ -160,7 +160,7 @@ All engines correctly implement: **Verification**: Ran `TestInterfaceSegregation` - all tests pass. -**Assessment**: ✅ **Excellent**. Interface compliance is enforced by tests. +**Assessment**: ✅ Interface compliance is enforced by tests. ### Code Organization @@ -170,7 +170,7 @@ Engine code follows established patterns: - Tests in `*_engine_test.go` - Clear separation of concerns -**Assessment**: ✅ **Well-organized**. Easy to navigate and understand. +**Assessment**: ✅ Code is organized per engine, with shared helpers in `engine_helpers.go`. ## Security Review @@ -271,7 +271,7 @@ Engine code includes: - ✅ Best practices - ✅ Troubleshooting -**Assessment**: ✅ **Excellent**. Developers have comprehensive guidance. +**Assessment**: ✅ Developers have comprehensive guidance. ## Recommendations diff --git a/scratchpad/engine-review-summary.md b/scratchpad/engine-review-summary.md index 6c40593985e..08414108e53 100644 --- a/scratchpad/engine-review-summary.md +++ b/scratchpad/engine-review-summary.md @@ -91,7 +91,7 @@ Completed comprehensive deep review of the agentic engine architecture, interfac ### Interface Design: ⭐⭐⭐⭐⭐ (5/5) -The interface hierarchy is well-designed: +The interface hierarchy follows the Interface Segregation Principle: ``` CodingAgentEngine (composite - backward compatibility) @@ -133,9 +133,9 @@ CodingAgentEngine (composite - backward compatibility) | Engine | Files | Rating | Notes | |--------|-------|--------|-------| -| Copilot | 7 | ⭐⭐⭐⭐⭐ | Excellent modular organization | -| Claude | 1 | ⭐⭐⭐⭐⭐ | Clean, comprehensive | -| Codex | 3 | ⭐⭐⭐⭐⭐ | TOML config, well-organized | +| Copilot | 7 | ⭐⭐⭐⭐⭐ | Modular organization (7 files) | +| Claude | 1 | ⭐⭐⭐⭐⭐ | Comprehensive single-file implementation | +| Codex | 3 | ⭐⭐⭐⭐⭐ | TOML config, 3-file structure | | Custom | 1 | ⭐⭐⭐⭐⭐ | Simple, focused | All implementations follow established patterns and are thoroughly tested.