[docs] Consolidate developer specifications into instructions file

[github-actions]

Developer Documentation Consolidation

This PR consolidates markdown specifications from the scratchpad/ directory into a unified .github/agents/developer.instructions.agent.md file.

Changes Made

• Analyzed 53 specification files from scratchpad/
• Fixed 37 tone issues (marketing → technical language)
• Added 9 Mermaid diagrams for visual clarity
• Ensured 45 code blocks all have proper language tags
• Consolidated into single instructions file (1,444 lines)

Consolidation Statistics

Metric	Value
Files analyzed	53
Total lines before	33,486
Total lines after	1,444
Consolidation ratio	4.3% (95.7% reduction)
Tone adjustments	37
Formatting fixes	69
Diagrams added	9

Files Modified

• Created: .github/agents/developer.instructions.agent.md

Sections Included

1. Core Architecture (four-layer security model, compilation flow)
2. Code Organization (file patterns, decision trees)
3. Validation Architecture (centralized vs domain-specific)
4. Safe Outputs System (security architecture, data flow)
5. Testing Guidelines (assert vs require, table-driven tests)
6. CLI Command Patterns (standard structure, conventions)
7. Error Handling (wrapping, collection, console output)
8. Security Best Practices (injection prevention, strict mode)
9. Workflow Patterns (refactoring strategies, runtime import)
10. MCP Integration (access control, server configuration)
11. Go Type Patterns (string enums, config structs, builders)
12. Quick Reference (commands, locations, decision trees)

Tone Improvements

Marketing language removed (20 instances):

• "simple/simplest" → "minimal", "straightforward", "direct"
• "easy" → "straightforward"
• "powerful" → specific technical descriptions
• "amazing/great" → factual descriptions

Vague language removed (17 instances):

• "just/only" → removed or made specific
• "very" → specific measurements
• "really" → factual statements

Visual Enhancements

Added 9 Mermaid diagrams:

• Four-Layer Security Model
• Compilation and Runtime Flow
• Code Organization Decision Tree
• Validation Architecture
• Safe Outputs Architecture
• Safe Outputs Data Flow (sequence)
• Workflow Refactoring Strategies
• Runtime Import Process (sequence)
• MCP Access Control Layers

Validation

✅ All markdown validated
✅ Mermaid diagrams render correctly
✅ All code blocks have language tags (45 blocks)
✅ Consistent technical tone
✅ Proper frontmatter
✅ Logical structure

Review Notes

Please review:

1. The consolidated instructions file for accuracy
2. Mermaid diagrams for correctness
3. Tone consistency throughout
4. Technical precision of descriptions

Discussion

See the discussion for detailed consolidation report: Search for "Developer Documentation Consolidation - 2026-02-11" in discussions.

Original Specifications

All original specification files remain in scratchpad/ for detailed reference and historical context. The consolidated file provides a curated, developer-focused view of the most important patterns and guidelines.

Comparison to Previous Consolidation

Previous consolidation (2026-02-10): 1,257 lines, 8 diagrams
Current consolidation (2026-02-11): 1,444 lines, 9 diagrams

Enhancements:

• Improved technical tone (removed all marketing language)
• Added additional Mermaid diagram
• Enhanced code examples with proper language tags
• Better coverage of all 53 specification files
• Improved decision tree representations

🤖 Generated with [Claude Code]((claude.com/redacted)

AI generated by Developer Documentation Consolidator

• expires on Feb 13, 2026, 12:19 PM UTC

[github-actions]

🔍 PR Triage Results

Category: docs | Risk: low | Priority: 30/100

Scores Breakdown

• Impact: 15/50 - Standard docs changes
• Urgency: 0/30 - Normal urgency
• Quality: 15/20 - CI pending, ready for review

📋 Recommended Action: BATCH REVIEW

📦 BATCH REVIEW AVAILABLE

This PR is part of batch-docs-001 along with:

• PR docs: fix tokens page build errors - stable anchor IDs and proper image containers #14937

These documentation PRs can be reviewed together for efficiency.

---

Triaged by PR Triage Agent on 2026-02-11 | Run #21904909325

AI generated by PR Triage Agent