[caveman] Optimize instruction verbosity — developer.instructions.md (2026-05-01)

.github/agents/developer.instructions.md

@@ -7,24 +7,6 @@ applyTo: "**/*"
 
 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
-
-- [Code Organization Patterns](#code-organization-patterns)
-- [Validation Architecture](#validation-architecture)
-- [Development Standards](#development-standards)
-- [String Processing](#string-processing)
-- [YAML Handling](#yaml-handling)
-- [Safe Output Messages](#safe-output-messages)
-- [Custom GitHub Actions](#custom-github-actions)
-- [Security Best Practices](#security-best-practices)
-- [Testing Framework](#testing-framework)
-- [Repo-Memory System](#repo-memory-system)
-- [Hierarchical Agent Management](#hierarchical-agent-management)
-- [Release Management](#release-management)
-- [Scope Hints for Complex Workflows](#scope-hints-for-complex-workflows)
-- [PR Deduplication Protocol](#pr-deduplication-protocol)
-- [Quick Reference](#quick-reference)
-
 ---
 
 ## Code Organization Patterns
@@ -87,9 +69,6 @@ graph TD
 - **Medium (200-500 lines)**: Domain-specific logic, focused features
 - **Large (500-1000 lines)**: Complex features, comprehensive implementations
 - **Very Large (1000+ lines)**: Consider splitting if not cohesive
-
-**Implementation**: See scratchpad/code-organization.md for complete guidelines
-
 ---
 
 ## Validation Architecture
@@ -165,47 +144,19 @@ graph TD
     F -->|Node.js| H[npm.go]
     F -->|Other| I[Create New Domain File]
 ```
-
-**Implementation**: See scratchpad/validation-architecture.md for complete architecture
-
 ---
 
 ## Development Standards
 
 ### Capitalization Guidelines
 
-```mermaid
-graph TD
-    A[Text to Capitalize?] --> B{Product Name?}
-    B -->|Yes| C[GitHub Agentic Workflows]
-    B -->|No| D{Feature Name?}
-    D -->|Yes| E[Use sentence case]
-    D -->|No| F{Code Element?}
-    F -->|Yes| G[Use as defined in code]
-    F -->|No| H[Follow standard conventions]
-```
-
 **Rules**:
 - **Product Name**: "GitHub Agentic Workflows" (always capitalize)
 - **Feature Names**: Use sentence case (e.g., "safe output messages")
 - **File Names**: Use lowercase with hyphens (e.g., `code-organization.md`)
 - **Code Elements**: Follow language conventions (e.g., `camelCase` in JavaScript, `snake_case` in Python)
-
-**Implementation**: See scratchpad/capitalization.md and `cmd/gh-aw/capitalization_test.go`
-
 ### Breaking Change Rules
 
-```mermaid
-graph TD
-    A[Making a Change?] --> B{Affects Public API?}
-    B -->|Yes| C{Backward Compatible?}
-    B -->|No| D[Not Breaking]
-    C -->|Yes| D
-    C -->|No| E[BREAKING CHANGE]
-    E --> F[Document in Changeset]
-    E --> G[Update Major Version]
-```
-
 **Breaking Changes**:
 - Removing or renaming CLI commands, flags, or options
 - Changing default behavior that users depend on
@@ -217,9 +168,6 @@ graph TD
 - Adding new output formats
 - Internal refactoring with same external behavior
 - Adding new features that don't affect existing functionality
-
-**Implementation**: See scratchpad/breaking-cli-rules.md for complete rules
-
 ---
 
 ## String Processing
@@ -253,9 +201,6 @@ graph TD
 - `normalizeWhitespace()` - Standardizes whitespace (spaces, tabs, newlines)
 - `normalizeLineEndings()` - Converts CRLF to LF
 - `normalizeMarkdown()` - Standardizes markdown formatting
-
-**Implementation**: See scratchpad/string-sanitization-normalization.md and `pkg/workflow/strings.go`
-
 ---
 
 ## YAML Handling
@@ -283,9 +228,6 @@ err := yaml.Unmarshal(data, &workflow)
 - Workflow triggers: `on`, `push`, `pull_request`
 - Boolean values: `yes`, `no`, `true`, `false`, `on`, `off`
 - Null values: `null`, `~`
-
-**Implementation**: See scratchpad/yaml-version-gotchas.md and `pkg/workflow/compiler.go`
-
 ---
 
 ## Safe Output Messages
@@ -319,9 +261,6 @@ safe_outputs:
       ---
       > AI generated by [WorkflowName](run_url)
 ```
-
-**Implementation**: See scratchpad/safe-output-messages.md and `pkg/workflow/safe_outputs.go`
-
 ---
 
 ## Custom GitHub Actions
@@ -355,9 +294,6 @@ actions/
     ├── js/
     └── sh/
 ```
-
-**Implementation**: See scratchpad/actions.md and `pkg/cli/actions_build_command.go`
-
 ---
 
 ## Security Best Practices
@@ -399,28 +335,12 @@ permissions:
 steps:
   - uses: actions/checkout@a1b2c3d4... # Pinned SHA
 ```
-
-**Implementation**: See scratchpad/github-actions-security-best-practices.md and scratchpad/template-injection-prevention.md
-
 ---
 
 ## Testing Framework
 
 ### Test Strategy
 
-```mermaid
-graph TD
-    A[Code Changes] --> B[Unit Tests]
-    A --> C[Integration Tests]
-    A --> D[Security Tests]
-    B --> E[Fast Feedback]
-    C --> F[End-to-End Validation]
-    D --> G[Regression Prevention]
-    E --> H[CI Pipeline]
-    F --> H
-    G --> H
-```
-
 ### Test Types
 
 | Test Type | Purpose | Location | Run Frequency |
@@ -458,9 +378,6 @@ make update-golden
 - ✅ Adding new columns or fields to tables
 - ❌ Tests fail unexpectedly during development
 - ❌ Making unrelated code changes
-
-**Implementation**: See scratchpad/visual-regression-testing.md and `pkg/console/golden_test.go`
-
 ---
 
 ## Repo-Memory System
@@ -516,9 +433,6 @@ repo-memory:
 - Maximum file count limits
 - Allowed/blocked file patterns
 - Size and count tracking in commit messages
-
-**Implementation**: See scratchpad/repo-memory.md and `pkg/workflow/repo_memory.go`
-
 ---
 
 ## Hierarchical Agent Management
@@ -527,34 +441,12 @@ The hierarchical agent system provides meta-orchestration capabilities to manage
 
 ### Meta-Orchestrator Architecture
 
-```mermaid
-graph TD
-  A[Meta-Orchestrators] --> B[Orchestration Manager]
-    A --> C[Workflow Health Manager]
-    A --> D[Agent Performance Analyzer]
-
-  B --> E[Coordinator 1]
-  B --> F[Coordinator 2]
-  B --> G[Coordinator N]
-
-    C --> H[Workflow Monitoring]
-    C --> I[Dependency Mapping]
-    C --> J[Issue Creation]
-
-    D --> K[Quality Assessment]
-    D --> L[Performance Metrics]
-    D --> M[Improvement Reports]
-```
-
 ### Meta-Orchestrator Roles
 
 | Role | File | Purpose | Schedule |
 |------|------|---------|----------|
 | **Workflow Health Manager** | `workflow-health-manager.md` | Monitor workflow health | Daily |
 | **Agent Performance Analyzer** | `agent-performance-analyzer.md` | Analyze agent quality | Daily |
-
-**Implementation**: See scratchpad/agents/hierarchical-agents.md and `.github/workflows/` meta-orchestrator files
-
 ---
 
 ## Release Management
@@ -594,9 +486,6 @@ For manual feature testing in pull requests:
 2. Add test scenarios as comments in PR
 3. Dev Hawk will analyze and verify behavior
 4. Do not merge dev.md changes - it remains a reusable test harness
-
-**Implementation**: See scratchpad/changesets.md and scratchpad/end-to-end-feature-testing.md
-
 ---
 
 ## Scope Hints for Complex Workflows
@@ -660,9 +549,6 @@ Before submitting a complex workflow request, confirm you have specified:
 - [ ] **Success/failure criterion** — e.g. coverage ≥ 80%, zero high-severity CVEs
 - [ ] **Output destination** — e.g. PR comment, issue, Slack notification, artifact
 - [ ] **Scope boundaries** — e.g. only changed files, only the `src/` directory
-
-**Implementation**: See discussion [#19488](https://github.com/github/gh-aw/discussions/19488) for background on timeout root causes.
-
 ---
 
 ## PR Deduplication Protocol