[Feature]: v3-beta Provide an official AGENTS.md template for oh-my-opencode usage (orchestration + agent calling conventions)

[OCPdev25]

Prerequisites

• I have searched existing issues and discussions to avoid duplicates
• This feature request is specific to oh-my-opencode (not OpenCode core)
• I have read the documentation

Problem Description

Across different main agents/models (Opus, Gemini, GPT, etc.), I’ve found that agents often don’t consistently follow oh-my-opencode “how to use this harness” guidance unless I explicitly encode it in an AGENTS.md rules file.

In practice, I had to iteratively “smoke test” + update my AGENTS.md with concrete rules like:

• what the orchestrator should do vs. should delegate
• which subagent to call (and when a “subtype” should be invoked instead of the parent agent)
• how to call subagents correctly during orchestration/planning
• phrasing patterns that work better (e.g., “ensure X” vs “don’t do Y”, since some models tend to chase the negative instruction)

This worked extremely well once I got it right: “read AGENTS.md first” led to less steering and better tool/agent utilization—more reliably than relying on skills alone.

This request is not asking the project to manage/own users’ personal AGENTS.md content. I’m asking for a public template that users can copy/customize so there’s a stable “spec” for using oh-my-opencode properly.

(Separate but related: there’s an existing feature request about agents updating AGENTS.md automatically; this request is specifically about providing a starter template users can adopt/customize.) :contentReference

Proposed Solution

Ship an official, versioned AGENTS.md template specifically for oh-my-opencode usage, plus documentation that recommends it.

Concrete deliverables:

1. Add a template file to the repo (example names):
   • assets/AGENTS.oh-my-opencode.template.md
   • or docs/AGENTS_TEMPLATE.md
2. Include guidance sections tailored to oh-my-opencode:
   • “Orchestrator contract” (delegate-first, when to do work vs. route tasks)
   • “Agent selection rules” (agent vs subtype conventions, common pitfalls)
   • “Calling conventions” (how to invoke subagents, when to switch)
   • “Instruction phrasing” (positive/affirmative constraints; “ensure X” patterns)
   • “Workflow loop” (plan → delegate → verify → summarize; avoid thrashing)
3. Optional: integrate it into existing initialization flows:
   • OpenCode already supports AGENTS.md as its rules file and provides /init to create it
   • oh-my-opencode could offer a /init-omo or extend its onboarding docs to say: “copy this template into your repo and customize”

Why AGENTS.md: it’s injected into the agent’s context by OpenCode rules, so it is “always-on” guidance.

Alternatives Considered

• Skills-only approach: skills are discoverable but loaded on-demand via the skill tool, so you don’t get the same always-on behavioral spec unless the agent chooses to load it. :contentReference
• Just add docs: docs help humans, but in practice the agent still benefits from a concrete in-context contract (AGENTS.md) it must read first.
• Hardcode more system prompt: brittle + less user-customizable; template keeps ownership with users.

Alternatives Considered

• Skills-only approach: skills are discoverable but loaded on-demand via the skill tool, so you don’t get the same always-on behavioral spec unless the agent chooses to load it.
• Just add docs: docs help humans, but in practice the agent still benefits from a concrete in-context contract (AGENTS.md) it must read first.
• Hardcode more system prompt: brittle + less user-customizable; template keeps ownership with users.

Doctor Output (Optional)

Installation
────────────────────────────────────────
  ✓ OpenCode Installation → 1.1.8
      • Path: /Users//.bun/bin/opencode
  ✓ Plugin Registration → Registered
      • Config: /Users//.config/opencode/opencode.json

Configuration
────────────────────────────────────────
  ✓ Configuration Validity → Valid JSON config
      • Path: /Users//.config/opencode/oh-my-opencode.json

Authentication
────────────────────────────────────────
  ✓ Anthropic (Claude) Auth → Auth plugin available
      • Run: opencode auth login (select Anthropic)
  ✓ OpenAI (ChatGPT) Auth → Auth plugin available
      • Plugin: opencode-openai-codex-auth
  ✓ Google (Gemini) Auth → Auth plugin available
      • Plugin: opencode-antigravity-auth

Dependencies
────────────────────────────────────────
  ✓ AST-Grep CLI → ast-grep 0.40.3
      • Path: /Users//.config/opencode/node_modules/.bin/sg
  ⚠ AST-Grep NAPI → Not installed (optional)
      • Will use CLI fallback if available
  ✓ Comment Checker
      • Path: /Users//.config/opencode/node_modules/.bin/comment-checker

Tools & Servers
────────────────────────────────────────
  ✓ GitHub CLI → 2.72.0 - authenticated as OCPdev25
      • Path: /opt/homebrew/bin/gh
      • Account: 
      • Scopes: admin:public_key, gist, read:org, repo
  ⚠ LSP Servers → No LSP servers detected
      • LSP tools will have limited functionality
      • Missing: typescript-language-server
      • Missing: pyright
      • Missing: rust-analyzer
      • Missing: gopls
  ✓ Built-in MCP Servers → 2 built-in servers enabled
      • Enabled: context7
      • Enabled: grep_app
  ○ User MCP Configuration → No user MCP configuration found
      • Optional: Add .mcp.json for custom MCP servers

Updates
────────────────────────────────────────
  ✓ Version Status → Up to date (3.0.0-beta.1)
      • Latest: 2.14.0

Summary
────────────────────────────────────────
  11 passed, 0 failed, 2 warnings, 1 skipped
  Total: 14 checks in 2970ms

⚠ All systems operational with warnings.
`

Additional Context

OpenCode’s rules system explicitly supports AGENTS.md for always-on behavioral instructions (similar to CLAUDE.md / Cursor rules).
Since skills are on-demand, an AGENTS.md-based template gives users a stable “contract” that works across models/providers with less steering.

contentReference:
[1]: https://opencode.ai/docs/rules/ "Rules | OpenCode"
[2]: https://opencode.ai/docs/skills/ "Agent Skills | OpenCode"
[3]: #598 "[Feature]: It would be great if agents will be able to update AGENTS.md · Issue #598 · code-yeongyu/oh-my-opencode · GitHub"
[4]: #605 "[Feature]: Leverage the claude code intellij plugin · Issue #605 · code-yeongyu/oh-my-opencode · GitHub"

Feature Type

Other

Contribution

• I'm willing to submit a PR for this feature
• I can help with testing
• I can help with documentation

[JohnC0de]

Seems a good/valid improvement