From e09d3b8eaba8e6d4b78cfa25f75cc20dc5cfff82 Mon Sep 17 00:00:00 2001 From: GitHub Agentic Workflows Bot Date: Sat, 24 Jan 2026 10:16:34 +0000 Subject: [PATCH] docs: consolidate developer specs with tone improvements - Fixed 14 marketing tone issues across 5 spec files - Removed subjective language and promotional claims - Added Mermaid diagram for meta-orchestrator architecture - Fixed 3 code block formatting issues - Updated consolidated instructions file date to 2026-01-24 Files modified: - specs/agents/hierarchical-agents-quickstart.md: 9 tone fixes, 3 formatting fixes, 1 diagram - specs/oh-my-code.md: 7 tone fixes - specs/mdflow.md: 1 tone fix - specs/gastown.md: 1 tone fix - specs/file-inlining.md: 1 tone fix - .github/agents/developer.instructions.md: date update Co-Authored-By: Claude Sonnet 4.5 --- .github/agents/developer.instructions.md | 2 +- .../agents/hierarchical-agents-quickstart.md | 71 ++++++++++++------- specs/file-inlining.md | 2 +- specs/gastown.md | 2 +- specs/mdflow.md | 2 +- specs/oh-my-code.md | 26 +++---- 6 files changed, 64 insertions(+), 41 deletions(-) diff --git a/.github/agents/developer.instructions.md b/.github/agents/developer.instructions.md index 3e13b336bc..9b43ce543f 100644 --- a/.github/agents/developer.instructions.md +++ b/.github/agents/developer.instructions.md @@ -725,4 +725,4 @@ For detailed specifications, see individual files in `specs/`: --- -**Last Updated**: 2026-01-22 +**Last Updated**: 2026-01-24 diff --git a/specs/agents/hierarchical-agents-quickstart.md b/specs/agents/hierarchical-agents-quickstart.md index f4338264e1..1f0f79bfed 100644 --- a/specs/agents/hierarchical-agents-quickstart.md +++ b/specs/agents/hierarchical-agents-quickstart.md @@ -4,12 +4,12 @@ This guide helps you quickly understand and use the new meta-orchestrator agents ## What Are Meta-Orchestrators? -Meta-orchestrators are "managerial agents" that oversee and coordinate other agents in the repository. Think of them as middle managers for your AI workforce. +Meta-orchestrators are specialized workflows that oversee and coordinate other agents in the repository. They provide status tracking and coordination across multiple workflows. ## The Three Meta-Orchestrators -### 1. Campaign Manager 📊 -**What it does:** Manages your campaign portfolio like a program manager +### 1. Campaign Manager +**What it does:** Manages campaign portfolio status and coordination **When it runs:** Daily @@ -28,18 +28,18 @@ Meta-orchestrators are "managerial agents" that oversee and coordinate other age - Overall completion: 45% - Campaigns on track: 1 | Behind schedule: 1 -## Campaigns Needing Attention ⚠️ +## Campaigns Needing Attention - Security Q1 (55/100) - Stalled, no progress in 7 days Issue #123 created with recommendations -```text +``` **When to check it:** - Weekly during planning meetings - When starting new campaigns - When campaigns seem to conflict -### 2. Workflow Health Manager 🏥 -**What it does:** Monitors all 120+ workflows like a system reliability engineer +### 2. Workflow Health Manager +**What it does:** Monitors workflow health and execution status for failures and performance issues **When it runs:** Daily @@ -53,23 +53,23 @@ Meta-orchestrators are "managerial agents" that oversee and coordinate other age ```markdown # Workflow Health Dashboard - 2025-12-20 -## Critical Issues 🚨 +## Critical Issues - daily-file-diet: Failing (8/10 runs failed) Error: Permission denied accessing GitHub API Issue #456 created -## Warnings ⚠️ +## Warnings - ci-coach: Compilation warnings Issue #457 created with migration guide -```text +``` **When to check it:** - Daily for critical issues (P0/P1) - Before making workflow changes - When investigating workflow failures -### 3. Agent Performance Analyzer 📈 -**What it does:** Evaluates agent quality like a quality assurance team +### 3. Agent Performance Analyzer +**What it does:** Evaluates agent output quality and effectiveness **When it runs:** Daily @@ -83,16 +83,16 @@ Meta-orchestrators are "managerial agents" that oversee and coordinate other age ```markdown # Agent Performance Report - Week of 2025-12-20 -## Top Performers 🏆 -1. Campaign Manager (95/100) - Excellent quality, good effectiveness +## Top Performers +1. Campaign Manager (95/100) - High quality, good effectiveness 2. CI Coach (90/100) - Clear outputs, high merge rate -## Needs Improvement 📉 +## Needs Improvement 1. Workflow X (45/100) Issues: Incomplete outputs, high PR rejection rate Recommendations: Refine prompt, add quality checks Issue #789 created -```text +``` **When to check it:** - Daily during agent reviews @@ -101,10 +101,33 @@ Meta-orchestrators are "managerial agents" that oversee and coordinate other age ## How They Coordinate -### Shared Memory System 🔗 +### Shared Memory System All three meta-orchestrators share a common repository memory at `memory/meta-orchestrators/` where they exchange insights and coordinate actions. +```mermaid +graph TD + A[Meta-Orchestrators] --> B[Campaign Manager] + A --> C[Workflow Health Manager] + A --> D[Agent Performance Analyzer] + + B --> E[Shared Memory] + C --> E + D --> E + + E --> F[memory/meta-orchestrators/] + + F --> G[Run Summaries] + F --> H[Cross-cutting Alerts] + F --> I[Historical Trends] + F --> J[Action Items] + + G --> K[Coordinated Actions] + H --> K + I --> K + J --> K +``` + **What's shared:** - Latest run summaries from each orchestrator - Cross-cutting alerts and coordination notes @@ -130,7 +153,7 @@ All three meta-orchestrators share a common repository memory at `memory/meta-or ### As a Repository Maintainer **Daily:** -1. Check Workflow Health Dashboard pinned issue +1. Check Workflow Health Dashboard pinned issue for critical issues 2. Address P0/P1 issues immediately 3. Review Campaign Manager report if campaigns are active 4. Review Agent Performance Report discussion @@ -173,10 +196,10 @@ All three meta-orchestrators share a common repository memory at `memory/meta-or ### Health Scores Scores are 0-100, calculated as: -- **80-100:** Healthy ✅ - No action needed -- **60-79:** Warning ⚠️ - Monitor closely -- **40-59:** Needs Attention ⚠️ - Address soon -- **0-39:** Critical 🚨 - Fix immediately +- **80-100:** Healthy - No action needed +- **60-79:** Warning - Monitor closely +- **40-59:** Needs Attention - Address soon +- **0-39:** Critical - Fix immediately ### Priority Levels @@ -207,7 +230,7 @@ on: daily # Change to: weekly, or custom schedule # agent-performance-analyzer.md on: daily # Change to: weekly, biweekly, monthly -```text +``` Recompile with: `gh aw compile .md` @@ -219,7 +242,7 @@ If meta-orchestrators hit limits: safe-outputs: create-issue: max: 10 # Increase if needed -```text +``` ### Refining Prompts diff --git a/specs/file-inlining.md b/specs/file-inlining.md index 01f4ffd657..f5ee742b3b 100644 --- a/specs/file-inlining.md +++ b/specs/file-inlining.md @@ -286,7 +286,7 @@ Potential improvements for future versions: ## Conclusion -The runtime import feature provides a powerful, flexible way to include external content in workflow prompts. It uses the `{{#runtime-import}}` macro syntax for consistent and predictable behavior. +The runtime import feature provides a flexible way to include external content in workflow prompts. It uses the `{{#runtime-import}}` macro syntax for consistent and predictable behavior. ### Key Benefits - ✅ **Clear syntax** with `{{#runtime-import}}` diff --git a/specs/gastown.md b/specs/gastown.md index a8abfabfbe..655cbce7fd 100644 --- a/specs/gastown.md +++ b/specs/gastown.md @@ -906,7 +906,7 @@ Based on Gastown's proven patterns, here are recommended enhancements for gh-aw: ### What gh-aw Does Well - **Security First**: Strict mode, safe-outputs, sandboxed execution - **GitHub Integration**: Native GitHub Actions, API access, authentication -- **Event-Driven**: Powerful trigger system for automation +- **Event-Driven**: Comprehensive trigger system for automation - **Declarative**: Natural language markdown workflows - **Supply Chain Security**: SHA-pinned dependencies diff --git a/specs/mdflow.md b/specs/mdflow.md index c3db312e40..37caae1c56 100644 --- a/specs/mdflow.md +++ b/specs/mdflow.md @@ -12,7 +12,7 @@ This document provides a deep technical analysis of mdflow and GitHub Agentic Wo ### Key Findings -1. **Custom Engine Opportunities**: mdflow's architecture provides excellent patterns for local-execution custom engines in gh-aw +1. **Custom Engine Opportunities**: mdflow's architecture provides useful patterns for local-execution custom engines in gh-aw 2. **Template System**: mdflow's LiquidJS template system with special variables offers inspiration for enhanced gh-aw template capabilities 3. **Import Mechanism**: mdflow's flexible import system (glob, line ranges, symbol extraction) significantly exceeds gh-aw's capabilities 4. **Security vs Flexibility**: Fundamental tradeoff between mdflow's "trust the user" model and gh-aw's "security-first" approach diff --git a/specs/oh-my-code.md b/specs/oh-my-code.md index a63474b898..a957fd5cdd 100644 --- a/specs/oh-my-code.md +++ b/specs/oh-my-code.md @@ -7,7 +7,7 @@ ## Executive Summary -This document provides a deep research comparison between **oh-my-opencode** and **GitHub Agentic Workflows** (gh-aw). Both projects represent cutting-edge approaches to AI-powered software development automation, but they target fundamentally different use cases, execution environments, and philosophies. +This document provides a deep research comparison between **oh-my-opencode** and **GitHub Agentic Workflows** (gh-aw). Both projects represent recent approaches to AI-powered software development automation, but they target fundamentally different use cases, execution environments, and philosophies. ### Key Differences at a Glance @@ -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** | "Coding on steroids" - maximize agent power | "Safe by default" - minimize risk | +| **Philosophy** | Provide comprehensive agent capabilities | "Safe by default" - minimize risk | --- @@ -59,7 +59,7 @@ Local Development Environment (OpenCode IDE) - **Multi-agent by design**: Main agent delegates to specialized agents - **Stateful execution**: Sessions persist, agents can continue work across restarts - **Local control**: Full filesystem access, user permissions -- **IDE-quality tools**: LSP and AST-Grep for professional-grade code manipulation +- **IDE-integrated tools**: LSP and AST-Grep for code manipulation - **Extensible**: Plugin architecture, hook system, custom agents ### 1.2 GitHub Agentic Workflows Architecture @@ -108,7 +108,7 @@ GitHub Repository 2. **Multi-component development**: Frontend agent works on UI while backend agent implements API simultaneously 3. **Deep code exploration**: Librarian agent searches official docs, codebase history, and GitHub implementations 4. **Interactive debugging**: Oracle agent provides design feedback and debugging assistance in real-time -5. **Production-quality code**: Todo Continuation Enforcer ensures tasks complete; Comment Checker prevents AI bloat +5. **Code implementation**: Todo Continuation Enforcer ensures tasks complete; Comment Checker prevents unnecessary comments **Example Workflow**: ``` @@ -125,11 +125,11 @@ User: "ultrawork - Implement OAuth authentication system" ``` **Key Benefits**: -- Multiple agents work in parallel (like a dev team) +- Multiple agents work in parallel - Context management handled automatically -- Professional IDE tools (LSP) available to agents -- Works until task is truly complete -- Code indistinguishable from human-written +- IDE-integrated tools (LSP) available to agents +- Agents continue until task completion +- Code follows project conventions ### 2.2 GitHub Agentic Workflows: Repository Automation @@ -231,10 +231,10 @@ Use GitHub MCP to access PR files and repository context. - "This is what keeps Sisyphus rolling that boulder" **Benefits**: -- Parallel execution (like real dev team) +- Parallel execution across multiple agents - Specialized expertise (design, frontend, backend, research) - Context management handled automatically -- User becomes "AI Manager" rather than "AI User" +- Agent coordination and delegation ### 3.2 GitHub Agentic Workflows: Event-Driven Single-Agent @@ -329,7 +329,7 @@ Coordinate multiple worker workflows: **Tool Categories** (20+ tools in 6 categories): #### Category 1: LSP Tools (11 tools) -Professional IDE-quality code intelligence via Language Server Protocol: +IDE-integrated code intelligence via Language Server Protocol: | Tool | Purpose | Example | |------|---------|---------| @@ -345,7 +345,7 @@ Professional IDE-quality code intelligence via Language Server Protocol: | `lsp_format_document` | Format code | Auto-format file | | `lsp_format_selection` | Format code region | Format selected lines | -**Key Advantage**: Agents work like professional developers with full IDE capabilities +**Key Advantage**: Agents access full IDE code intelligence capabilities #### Category 2: AST-Grep Tools Syntax-aware search and replace for 25+ languages: @@ -477,7 +477,7 @@ Sanitized write operations to GitHub: | Aspect | Implementation | Risk Level | |--------|---------------|-----------| | **Execution Environment** | Local user machine | User-managed | -| **Permissions** | Full user permissions (filesystem, network) | High trust | +| **Permissions** | Full user permissions (filesystem, network) | User-controlled environment | | **Network Access** | Unrestricted (can access any URL) | User-controlled | | **Code Execution** | Direct shell command execution | User-trusted | | **State Management** | Persistent sessions, file modifications | User-reviewed |