Skip to content

[docs] Consolidate developer specifications with tone improvements #11617

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 1 commit into from
Jan 24, 2026
Merged

[docs] Consolidate developer specifications with tone improvements #11617

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/agents/developer.instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -725,4 +725,4 @@ For detailed specifications, see individual files in `specs/`:

---

**Last Updated**: 2026-01-22
**Last Updated**: 2026-01-24
71 changes: 47 additions & 24 deletions specs/agents/hierarchical-agents-quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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 <workflow>.md`

Expand All @@ -219,7 +242,7 @@ If meta-orchestrators hit limits:
safe-outputs:
create-issue:
max: 10 # Increase if needed
```text
```

### Refining Prompts

Expand Down
2 changes: 1 addition & 1 deletion specs/file-inlining.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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}}`
Expand Down
2 changes: 1 addition & 1 deletion specs/gastown.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion specs/mdflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
26 changes: 13 additions & 13 deletions specs/oh-my-code.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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 |

---

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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**:
```
Expand All @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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 |
|------|---------|---------|
Expand All @@ -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:
Expand Down Expand Up @@ -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 |
Expand Down