From bd01975d3fce890b084d9c3e93b9421d2557fd5c Mon Sep 17 00:00:00 2001 From: Arye Kogan Date: Sat, 7 Feb 2026 22:12:52 +0200 Subject: [PATCH 01/10] docs: add MAINTAINERS.md with roles and triage expectations --- MAINTAINERS.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 MAINTAINERS.md diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 0000000..bd623b5 --- /dev/null +++ b/MAINTAINERS.md @@ -0,0 +1,35 @@ +# Maintainers + +This document outlines the maintainership roles, triage expectations, and response windows for the `benchmarks` repository. + +## Roles + +- **Lead Maintainers**: Responsible for the overall direction, architecture, and final approval of major changes. +- **Maintainers**: Responsible for reviewing pull requests, triaging issues, and maintaining specific components (e.g., parity runner, benchmark scripts). +- **Triage**: Responsible for initial issue screening, labeling, and routing questions to [Discussions](https://github.com/go-modkit/benchmarks/discussions). + +## Triage Expectations + +We aim to provide timely feedback on community contributions while balancing other project priorities. + +| Activity | Initial Response Window | Goal | +|----------|-------------------------|------| +| **New Issues** | 2-3 business days | Acknowledge, label, and request missing info. | +| **Pull Requests** | 3-5 business days | Provide initial review or feedback. | +| **Discussions** | Best effort | Community-driven; maintainers participate as time permits. | + +*Note: Response windows are targets, not guarantees. We appreciate your patience.* + +## Escalation Paths + +### Security Vulnerabilities +Do not report security vulnerabilities via public issues. Follow the [Security Policy](SECURITY.md) for private disclosure. + +### Urgent Issues +For critical regressions or build failures impacting the main branch, please mention a maintainer in the relevant issue or PR. + +## Governance + +Decisions are made through consensus among maintainers. For major architectural changes, a design document (RFC) should be submitted to `docs/design/` for review. + +See [CONTRIBUTING.md](CONTRIBUTING.md) for the technical contribution process. From ec0fbbb170ae1a2ec1f09a4ba49fa9f2ae42f3f8 Mon Sep 17 00:00:00 2001 From: Arye Kogan Date: Sat, 7 Feb 2026 22:12:54 +0200 Subject: [PATCH 02/10] docs: add OMO setup guide with tmux and category config --- docs/guides/omo-setup.md | 118 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 docs/guides/omo-setup.md diff --git a/docs/guides/omo-setup.md b/docs/guides/omo-setup.md new file mode 100644 index 0000000..e96dbc9 --- /dev/null +++ b/docs/guides/omo-setup.md @@ -0,0 +1,118 @@ +# Oh-My-OpenCode (OMO) Setup Guide + +This guide provides the recommended setup for Oh-My-OpenCode (OMO) to maximize productivity with parallel agents, visual multi-agent execution, and optimized model mapping. + +## Prerequisites + +### Tmux Integration +To use the visual multi-agent execution (where background agents spawn in separate panes), you must meet these requirements: +1. **Run inside Tmux**: OpenCode must be executed within an active tmux session. +2. **Server Mode**: OpenCode must run with the `--port` flag (e.g., `opencode --port 4096`). This enables the subagent pane spawning mechanism. +3. **Tmux Installed**: Ensure `tmux` is available in your system PATH. + +## Recommended Configuration + +Create or update your `oh-my-opencode.jsonc` (or `oh-my-opencode.json`) with these recommended settings. + +```jsonc +{ + "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json", + + // 1. Category Model Mapping + // Optimizes model selection based on task type to balance cost and performance. + "categories": { + "quick": { + "model": "anthropic/claude-haiku-4-5", // Fast + cheap for trivial tasks + "description": "Trivial tasks - single file changes, typo fixes" + }, + "ultrabrain": { + "model": "openai/gpt-5.3-codex", // Deep logical reasoning + "variant": "xhigh" + }, + "writing": { + "model": "google/gemini-3-flash-preview", // Excellent for prose and docs + "textVerbosity": "high" + }, + "visual-engineering": { + "model": "google/gemini-3-pro-preview", // Best for UI/UX and styling + "is_unstable_agent": true + } + }, + + // 2. Background Concurrency + // Controls how many parallel background agents can run simultaneously. + "background_task": { + "defaultConcurrency": 5, + "providerConcurrency": { + "anthropic": 3, + "openai": 5, + "google": 10 + } + }, + + // 3. Tmux Settings + // Enables visual multi-agent execution in separate tmux panes. + "tmux": { + "enabled": true, + "layout": "main-vertical", + "main_pane_size": 60 + } +} +``` + +## Tmux Workflow (Recommended) + +To simplify the tmux + server mode workflow, add this function to your shell configuration (e.g., `~/.bashrc`, `~/.zshrc`, or `~/.config/fish/config.fish`). + +### Bash/Zsh +```bash +oc() { + local base_name=$(basename "$PWD") + local path_hash=$(echo "$PWD" | md5sum | cut -c1-4) + local session_name="${base_name}-${path_hash}" + + # Find available port starting from 4096 + local port=4096 + while [ $port -lt 5096 ]; do + if ! lsof -i :$port >/dev/null 2>&1; then + break + fi + port=$((port + 1)) + done + + export OPENCODE_PORT=$port + + if [ -n "$TMUX" ]; then + # Already inside tmux - just run with port + opencode --port $port "$@" + else + # Create tmux session and run opencode + local oc_cmd="OPENCODE_PORT=$port opencode --port $port $*; exec $SHELL" + if tmux has-session -t "$session_name" 2>/dev/null; then + tmux new-window -t "$session_name" -c "$PWD" "$oc_cmd" + tmux attach-session -t "$session_name" + else + tmux new-session -s "$session_name" -c "$PWD" "$oc_cmd" + fi + fi +} +``` + +## Non-Tmux Fallback + +If you cannot use Tmux, OMO still supports background agents, but they will run silently in the background without dedicated terminal panes. You can retrieve their output using the `background_output` tool or wait for system notifications upon completion. + +To disable tmux integration explicitly: +```json +{ + "tmux": { + "enabled": false + } +} +``` + +## Official Documentation + +For more detailed information, refer to the official Oh-My-OpenCode documentation: +- [Features Overview](https://github.com/code-yeongyu/oh-my-opencode/blob/dev/docs/features.md) +- [Configuration Guide](https://github.com/code-yeongyu/oh-my-opencode/blob/dev/docs/configurations.md) From 781e928ff03149060868f19fa50640c7aaccfbd1 Mon Sep 17 00:00:00 2001 From: Arye Kogan Date: Sat, 7 Feb 2026 22:14:15 +0200 Subject: [PATCH 03/10] chore(repo): add license and baseline trust signals --- LICENSE | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..92dabf7 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 go-modkit authors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. From b3ddc2457fff7e9bade78eb9f060de7782969d3e Mon Sep 17 00:00:00 2001 From: Arye Kogan Date: Sat, 7 Feb 2026 22:15:38 +0200 Subject: [PATCH 04/10] docs(repo): strengthen positioning and publication governance --- README.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/README.md b/README.md index b50d7c6..a559bdf 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,11 @@ # benchmarks +[![CI](https://github.com/go-modkit/benchmarks/actions/workflows/ci.yml/badge.svg)](https://github.com/go-modkit/benchmarks/actions/workflows/ci.yml) +[![Codecov](https://codecov.io/gh/go-modkit/benchmarks/branch/main/graph/badge.svg)](https://codecov.io/gh/go-modkit/benchmarks) +[![CodeQL](https://github.com/go-modkit/benchmarks/actions/workflows/codeql.yml/badge.svg)](https://github.com/go-modkit/benchmarks/actions/workflows/codeql.yml) +[![Go Report Card](https://goreportcard.com/badge/github.com/go-modkit/benchmarks)](https://goreportcard.com/report/github.com/go-modkit/benchmarks) +[![License](https://img.shields.io/github/license/go-modkit/benchmarks)](LICENSE) + Benchmark harness for framework parity and performance comparisons. ## What this repository does @@ -8,6 +14,23 @@ Benchmark harness for framework parity and performance comparisons. - stores declarative parity fixtures and seed data - provides benchmark orchestration scripts and report generation +## How this complements modkit + +This repository serves as the companion performance laboratory for [go-modkit/modkit](https://github.com/go-modkit/modkit). While modkit focuses on developer ergonomics and modular architecture, this harness ensures that those abstractions do not come at the cost of performance or correctness. + +By maintaining a strict parity-gate, we ensure that every framework implementation compared here—including modkit—adheres to the same API contract before a single request is timed. + +## Why trust these benchmarks + +We prioritize correctness and reproducibility over "hero numbers": + +- **Parity-Gated**: Benchmarks are automatically skipped if a target fails the API behavior contract. We only measure what is correct. +- **Reproducible**: All runs use Docker-based orchestration with pinned resource limits and standardized load profiles. +- **Transparent**: Raw metrics, environment fingerprints, and statistical variance are preserved for every run. +- **Policy-Driven**: Quality gates enforce statistical significance and schema validation for all artifacts. + +For detailed execution details and fairness principles, see our [Methodology](METHODOLOGY.md) and [Benchmark Workflow](docs/guides/benchmark-workflow.md). + ## Quickstart Run parity against a local target: From b762ba5e72403cae88e66c7104e17b1a05964e0b Mon Sep 17 00:00:00 2001 From: Arye Kogan Date: Sat, 7 Feb 2026 22:15:56 +0200 Subject: [PATCH 05/10] docs(repo): strengthen positioning and publication governance --- docs/guides/benchmark-publication-policy.md | 68 +++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 docs/guides/benchmark-publication-policy.md diff --git a/docs/guides/benchmark-publication-policy.md b/docs/guides/benchmark-publication-policy.md new file mode 100644 index 0000000..76223be --- /dev/null +++ b/docs/guides/benchmark-publication-policy.md @@ -0,0 +1,68 @@ +# Benchmark Publication and Reproducibility Policy + +This document defines the minimum disclosure requirements and operational bounds for publishable benchmark results generated by this harness. Adherence to this policy ensures that published claims are reproducible, statistically sound, and fair. + +## Minimum Disclosure Requirements + +Any public claim or report referencing benchmarks from this repository must include or link to the following artifacts from the `results/latest/` directory: + +### 1. Environment Manifest and Fingerprint +- **Artifacts**: `environment.manifest.json`, `environment.fingerprint.json` +- **Requirement**: Disclosure of the runner metadata, toolchain versions (Go, Python, Docker), and host environment characteristics. +- **Purpose**: Ensures results can be contextualized against the hardware and software stack used during the run. + +### 2. Schema Validation +- **Requirement**: All artifacts must pass `make benchmark-schema-validate`. +- **Purpose**: Guarantees that the raw metrics and summaries adhere to the versioned data contract. + +### 3. Quality Policy Compliance +- **Requirement**: The run must pass `make ci-benchmark-quality-check` as defined in `stats-policy.yaml`. +- **Metrics**: Must include at least RPS (median) and Latency (P50, P95, P99). +- **Variance**: Coefficient of Variation (CV) must stay within the thresholds defined in `stats-policy.yaml` (e.g., <10% for RPS). + +### 4. Parity and Skip Transparency +- **Requirement**: Any target implementation that failed the parity gate must be disclosed as "Skipped (Parity Failure)". +- **Purpose**: Prevents "cherry-picking" results from implementations that do not yet meet the functional contract. + +## Operational Bounds + +To maintain comparability and prevent resource exhaustion in CI/CD environments, publishable runs must stay within the following bounds (aligned with `benchmark-manual` workflow): + +| Parameter | Range | Default | +|-----------|-------|---------| +| **Runs per target** | 1 .. 10 | 3 | +| **Requests per run** | 50 .. 1000 | 300 | +| **Frameworks** | Subset of `modkit,nestjs,baseline,wire,fx,do` | - | + +Runs exceeding these bounds are considered "Experimental" and should not be used for official framework comparisons or public performance claims. + +## Reproducibility Workflow + +To generate a publishable report, follow the standard workflow: + +1. **Clean Environment**: Ensure a clean working tree and stable runtime versions. +2. **Execution**: + ```bash + make benchmark + ``` +3. **Validation**: + ```bash + make benchmark-schema-validate + make ci-benchmark-quality-check + ``` +4. **Reporting**: + ```bash + make report + ``` + +The resulting `results/latest/report.md` and `results/latest/summary.json` are the authoritative sources for publication. + +## Fairness and Interpretation + +- **Fairness**: All runs must adhere to the principles in [METHODOLOGY.md](../../METHODOLOGY.md). +- **Disclaimer**: Every published report must include the fairness disclaimer regarding cross-language comparisons and runtime effects. +- **Correctness First**: Performance data from a run with parity failures is invalid for comparative claims. + +## Policy Enforcement + +The `make publication-sync-check` command (and its CI equivalent) verifies that published artifacts align with the current methodology and versioned policy. From 6a29ad3b620525018b24ae3d1a544186fe57d70e Mon Sep 17 00:00:00 2001 From: Arye Kogan Date: Sat, 7 Feb 2026 22:16:51 +0200 Subject: [PATCH 06/10] docs(repo): strengthen positioning and publication governance --- README.md | 1 + docs/guides/AGENTS.md | 1 + docs/guides/repository-metadata.md | 55 ++++++++++++++++++++++++++++++ 3 files changed, 57 insertions(+) create mode 100644 docs/guides/repository-metadata.md diff --git a/README.md b/README.md index a559bdf..ad114d9 100644 --- a/README.md +++ b/README.md @@ -104,6 +104,7 @@ benchmarks/ - `docs/guides/parity-contract.md` - fixture and matcher semantics - `docs/guides/adding-scenarios.md` - how to add parity scenarios - `docs/guides/benchmark-workflow.md` - benchmark and reporting flow +- `docs/guides/repository-metadata.md` - repository metadata and positioning ## Contributing diff --git a/docs/guides/AGENTS.md b/docs/guides/AGENTS.md index 8811c99..2f2e47c 100644 --- a/docs/guides/AGENTS.md +++ b/docs/guides/AGENTS.md @@ -13,6 +13,7 @@ Operator-facing guides for parity contract usage, scenario authoring, and benchm |------|----------|-------| | Understand fixture semantics | `docs/guides/parity-contract.md` | Request/response schema and matcher tokens | | Add or modify scenarios safely | `docs/guides/adding-scenarios.md` | Endpoint-grouped workflow + checklist | +| Manage repo metadata | `docs/guides/repository-metadata.md` | Description, topics, and gh commands | | Run benchmark pipeline | `docs/guides/benchmark-workflow.md` | Standard, per-target, and artifact expectations | diff --git a/docs/guides/repository-metadata.md b/docs/guides/repository-metadata.md new file mode 100644 index 0000000..f896ef8 --- /dev/null +++ b/docs/guides/repository-metadata.md @@ -0,0 +1,55 @@ +# Repository Metadata Profile + +This document defines the GitHub repository metadata for the `benchmarks` project. Maintaining accurate metadata ensures discoverability and clear positioning within the `go-modkit` ecosystem. + +## Metadata Profile + +| Field | Value | +|-------|-------| +| **Description** | Parity-gated benchmark harness for API framework performance comparison. Ensures correctness via declarative contract fixtures before measuring throughput and latency. | +| **Topics** | `go`, `benchmark`, `api-parity`, `performance-testing`, `reproducibility`, `modkit`, `framework-comparison`, `api-contract`, `docker-orchestration`, `quality-gates` | +| **Homepage** | `https://github.com/go-modkit/benchmarks` | + +## Application Checklist + +### Automated (via GitHub CLI) + +If you have the `gh` CLI installed and authenticated, run the following command to apply the profile: + +```bash +gh repo edit go-modkit/benchmarks \ + --description "Parity-gated benchmark harness for API framework performance comparison. Ensures correctness via declarative contract fixtures before measuring throughput and latency." \ + --add-topic "go,benchmark,api-parity,performance-testing,reproducibility,modkit,framework-comparison,api-contract,docker-orchestration,quality-gates" \ + --homepage "https://github.com/go-modkit/benchmarks" +``` + +### Manual Fallback + +If the GitHub CLI is unavailable, follow these steps: + +1. Navigate to the repository on GitHub: [go-modkit/benchmarks](https://github.com/go-modkit/benchmarks) +2. Click on the **Settings** gear icon (or the "About" section edit icon on the main page). +3. In the **Description** field, paste: + > Parity-gated benchmark harness for API framework performance comparison. Ensures correctness via declarative contract fixtures before measuring throughput and latency. +4. In the **Website** field, paste: + > https://github.com/go-modkit/benchmarks +5. In the **Topics** section, add the following tags one by one: + - `go` + - `benchmark` + - `api-parity` + - `performance-testing` + - `reproducibility` + - `modkit` + - `framework-comparison` + - `api-contract` + - `docker-orchestration` + - `quality-gates` +6. Click **Save changes**. + +## Verification + +To verify the current metadata, run: + +```bash +gh repo view go-modkit/benchmarks --json description,repositoryTopics,homepage +``` From baef7aeedb2a10b56b9565de4c1587b56fc53b09 Mon Sep 17 00:00:00 2001 From: Arye Kogan Date: Sat, 7 Feb 2026 22:19:06 +0200 Subject: [PATCH 07/10] docs(repo): improve docs IA and cross-link integrity --- README.md | 10 ++++++++++ docs/guides/AGENTS.md | 5 ++++- 2 files changed, 14 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index ad114d9..86b609e 100644 --- a/README.md +++ b/README.md @@ -99,13 +99,23 @@ benchmarks/ ## Documentation +**Design & Architecture:** - `docs/design/002-api-parity-contract.md` - parity contract rationale - `docs/architecture.md` - repository architecture and execution flow + +**Guides:** - `docs/guides/parity-contract.md` - fixture and matcher semantics - `docs/guides/adding-scenarios.md` - how to add parity scenarios - `docs/guides/benchmark-workflow.md` - benchmark and reporting flow +- `docs/guides/benchmark-publication-policy.md` - minimum disclosure for publishable results +- `docs/guides/omo-setup.md` - OMO configuration recommendations - `docs/guides/repository-metadata.md` - repository metadata and positioning +**Governance:** +- `MAINTAINERS.md` - maintainership roles and triage expectations +- `CONTRIBUTING.md` - contribution process and validation commands +- `SECURITY.md` - security policy and vulnerability reporting + ## Contributing See `CONTRIBUTING.md` for contribution process and validation commands. diff --git a/docs/guides/AGENTS.md b/docs/guides/AGENTS.md index 2f2e47c..ed124de 100644 --- a/docs/guides/AGENTS.md +++ b/docs/guides/AGENTS.md @@ -13,8 +13,11 @@ Operator-facing guides for parity contract usage, scenario authoring, and benchm |------|----------|-------| | Understand fixture semantics | `docs/guides/parity-contract.md` | Request/response schema and matcher tokens | | Add or modify scenarios safely | `docs/guides/adding-scenarios.md` | Endpoint-grouped workflow + checklist | -| Manage repo metadata | `docs/guides/repository-metadata.md` | Description, topics, and gh commands | | Run benchmark pipeline | `docs/guides/benchmark-workflow.md` | Standard, per-target, and artifact expectations | +| Publish benchmark results | `docs/guides/benchmark-publication-policy.md` | Minimum disclosure for publishable results | +| Set up OMO workflow | `docs/guides/omo-setup.md` | OMO configuration and tmux setup | +| Manage repo metadata | `docs/guides/repository-metadata.md` | Description, topics, and gh commands | +| View maintainership info | `MAINTAINERS.md` | Roles, triage SLA, and escalation | ## CONVENTIONS From 95f56ff7999059568483f5cf56adec1ee7a99f01 Mon Sep 17 00:00:00 2001 From: Arye Kogan Date: Sat, 7 Feb 2026 22:20:46 +0200 Subject: [PATCH 08/10] docs: add rollout checklist and completion summary --- ROLLOUT_CHECKLIST.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 ROLLOUT_CHECKLIST.md diff --git a/ROLLOUT_CHECKLIST.md b/ROLLOUT_CHECKLIST.md new file mode 100644 index 0000000..c775416 --- /dev/null +++ b/ROLLOUT_CHECKLIST.md @@ -0,0 +1,38 @@ +# OSS Hardening and OMO Enablement - Rollout Checklist + +## Summary +All 16 tasks completed successfully. Work is ready for PR. + +## Branch +- **Branch**: feat/oss-hardening-and-omo-enablement +- **Worktree**: .worktrees/feat-oss-hardening/ +- **Commits**: 7 commits ahead of main + +## Files Changed +1. LICENSE (new) - MIT License +2. MAINTAINERS.md (new) - Governance doc +3. README.md - Badge row, modkit narrative, trust section +4. docs/guides/AGENTS.md - Guide index updates +5. docs/guides/benchmark-publication-policy.md (new) - Publication policy +6. docs/guides/omo-setup.md (new) - OMO config guide +7. docs/guides/repository-metadata.md (new) - Metadata profile + +## Suggested PR Sequence + +### PR 1: Legal and Baseline Trust + + +### PR 2: Governance and Positioning + + +### PR 3: OMO Setup Guide + + +## Post-Merge Actions +1. Apply GitHub metadata via commands in docs/guides/repository-metadata.md +2. Verify badges render correctly on README +3. Confirm docs/guides navigation works + +## Evidence +See .sisyphus/evidence/task-8-final-gate.txt for verification output. + From 70d5e7ec85c24386bbe32d50daa874fb81e37f8f Mon Sep 17 00:00:00 2001 From: Arye Kogan Date: Sat, 7 Feb 2026 22:33:55 +0200 Subject: [PATCH 09/10] chore(git): ignore local sisyphus state files --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index 92cb619..55a456c 100644 --- a/.gitignore +++ b/.gitignore @@ -13,3 +13,6 @@ coverage.out # Local worktrees .worktrees/ + +# Local OMO planning/state artifacts +.sisyphus/ From aa914559429dc7d59a13d3a4dd0b4dba4a4e182a Mon Sep 17 00:00:00 2001 From: Arye Kogan Date: Sat, 7 Feb 2026 22:38:48 +0200 Subject: [PATCH 10/10] docs: remove OMO setup guide and references --- README.md | 1 - ROLLOUT_CHECKLIST.md | 4 +- docs/guides/AGENTS.md | 1 - docs/guides/omo-setup.md | 118 --------------------------------------- 4 files changed, 1 insertion(+), 123 deletions(-) delete mode 100644 docs/guides/omo-setup.md diff --git a/README.md b/README.md index 86b609e..b9d4673 100644 --- a/README.md +++ b/README.md @@ -108,7 +108,6 @@ benchmarks/ - `docs/guides/adding-scenarios.md` - how to add parity scenarios - `docs/guides/benchmark-workflow.md` - benchmark and reporting flow - `docs/guides/benchmark-publication-policy.md` - minimum disclosure for publishable results -- `docs/guides/omo-setup.md` - OMO configuration recommendations - `docs/guides/repository-metadata.md` - repository metadata and positioning **Governance:** diff --git a/ROLLOUT_CHECKLIST.md b/ROLLOUT_CHECKLIST.md index c775416..2c9e47b 100644 --- a/ROLLOUT_CHECKLIST.md +++ b/ROLLOUT_CHECKLIST.md @@ -14,8 +14,7 @@ All 16 tasks completed successfully. Work is ready for PR. 3. README.md - Badge row, modkit narrative, trust section 4. docs/guides/AGENTS.md - Guide index updates 5. docs/guides/benchmark-publication-policy.md (new) - Publication policy -6. docs/guides/omo-setup.md (new) - OMO config guide -7. docs/guides/repository-metadata.md (new) - Metadata profile +6. docs/guides/repository-metadata.md (new) - Metadata profile ## Suggested PR Sequence @@ -35,4 +34,3 @@ All 16 tasks completed successfully. Work is ready for PR. ## Evidence See .sisyphus/evidence/task-8-final-gate.txt for verification output. - diff --git a/docs/guides/AGENTS.md b/docs/guides/AGENTS.md index ed124de..aa32981 100644 --- a/docs/guides/AGENTS.md +++ b/docs/guides/AGENTS.md @@ -15,7 +15,6 @@ Operator-facing guides for parity contract usage, scenario authoring, and benchm | Add or modify scenarios safely | `docs/guides/adding-scenarios.md` | Endpoint-grouped workflow + checklist | | Run benchmark pipeline | `docs/guides/benchmark-workflow.md` | Standard, per-target, and artifact expectations | | Publish benchmark results | `docs/guides/benchmark-publication-policy.md` | Minimum disclosure for publishable results | -| Set up OMO workflow | `docs/guides/omo-setup.md` | OMO configuration and tmux setup | | Manage repo metadata | `docs/guides/repository-metadata.md` | Description, topics, and gh commands | | View maintainership info | `MAINTAINERS.md` | Roles, triage SLA, and escalation | diff --git a/docs/guides/omo-setup.md b/docs/guides/omo-setup.md deleted file mode 100644 index e96dbc9..0000000 --- a/docs/guides/omo-setup.md +++ /dev/null @@ -1,118 +0,0 @@ -# Oh-My-OpenCode (OMO) Setup Guide - -This guide provides the recommended setup for Oh-My-OpenCode (OMO) to maximize productivity with parallel agents, visual multi-agent execution, and optimized model mapping. - -## Prerequisites - -### Tmux Integration -To use the visual multi-agent execution (where background agents spawn in separate panes), you must meet these requirements: -1. **Run inside Tmux**: OpenCode must be executed within an active tmux session. -2. **Server Mode**: OpenCode must run with the `--port` flag (e.g., `opencode --port 4096`). This enables the subagent pane spawning mechanism. -3. **Tmux Installed**: Ensure `tmux` is available in your system PATH. - -## Recommended Configuration - -Create or update your `oh-my-opencode.jsonc` (or `oh-my-opencode.json`) with these recommended settings. - -```jsonc -{ - "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json", - - // 1. Category Model Mapping - // Optimizes model selection based on task type to balance cost and performance. - "categories": { - "quick": { - "model": "anthropic/claude-haiku-4-5", // Fast + cheap for trivial tasks - "description": "Trivial tasks - single file changes, typo fixes" - }, - "ultrabrain": { - "model": "openai/gpt-5.3-codex", // Deep logical reasoning - "variant": "xhigh" - }, - "writing": { - "model": "google/gemini-3-flash-preview", // Excellent for prose and docs - "textVerbosity": "high" - }, - "visual-engineering": { - "model": "google/gemini-3-pro-preview", // Best for UI/UX and styling - "is_unstable_agent": true - } - }, - - // 2. Background Concurrency - // Controls how many parallel background agents can run simultaneously. - "background_task": { - "defaultConcurrency": 5, - "providerConcurrency": { - "anthropic": 3, - "openai": 5, - "google": 10 - } - }, - - // 3. Tmux Settings - // Enables visual multi-agent execution in separate tmux panes. - "tmux": { - "enabled": true, - "layout": "main-vertical", - "main_pane_size": 60 - } -} -``` - -## Tmux Workflow (Recommended) - -To simplify the tmux + server mode workflow, add this function to your shell configuration (e.g., `~/.bashrc`, `~/.zshrc`, or `~/.config/fish/config.fish`). - -### Bash/Zsh -```bash -oc() { - local base_name=$(basename "$PWD") - local path_hash=$(echo "$PWD" | md5sum | cut -c1-4) - local session_name="${base_name}-${path_hash}" - - # Find available port starting from 4096 - local port=4096 - while [ $port -lt 5096 ]; do - if ! lsof -i :$port >/dev/null 2>&1; then - break - fi - port=$((port + 1)) - done - - export OPENCODE_PORT=$port - - if [ -n "$TMUX" ]; then - # Already inside tmux - just run with port - opencode --port $port "$@" - else - # Create tmux session and run opencode - local oc_cmd="OPENCODE_PORT=$port opencode --port $port $*; exec $SHELL" - if tmux has-session -t "$session_name" 2>/dev/null; then - tmux new-window -t "$session_name" -c "$PWD" "$oc_cmd" - tmux attach-session -t "$session_name" - else - tmux new-session -s "$session_name" -c "$PWD" "$oc_cmd" - fi - fi -} -``` - -## Non-Tmux Fallback - -If you cannot use Tmux, OMO still supports background agents, but they will run silently in the background without dedicated terminal panes. You can retrieve their output using the `background_output` tool or wait for system notifications upon completion. - -To disable tmux integration explicitly: -```json -{ - "tmux": { - "enabled": false - } -} -``` - -## Official Documentation - -For more detailed information, refer to the official Oh-My-OpenCode documentation: -- [Features Overview](https://github.com/code-yeongyu/oh-my-opencode/blob/dev/docs/features.md) -- [Configuration Guide](https://github.com/code-yeongyu/oh-my-opencode/blob/dev/docs/configurations.md)