ringusing-ring-opencode

name	ring:using-ring-opencode
description	Skill discovery workflow and agent dispatch patterns for every conversation.
license	MIT
compatibility	opencode
metadata	{"trigger":"Every conversation start, before ANY task, when tempted to operate directly","skip_when":"Never skip - this skill is always mandatory"}

Using Ring Skills (OpenCode Edition)

Platform Compatibility

This skill library was originally designed for Claude Code and has been adapted for OpenCode. The following tool/concept mappings apply:

Claude Code Term	OpenCode Equivalent	Notes
Task tracking / TodoWrite	Task tracking / todo management	Use your platform's task tracking mechanism
Skill tool	Skill invocation	Read and execute skill files via your platform's skill system
Task(subagent_type=...)	Dispatch subagent / @agent-name	Launch specialized agents for focused work
AskUserQuestion	Prompt for input / ask the user	Request clarification from user when needed
N/A	Prompt / ask the user	Request clarification when you have doubts
.ring/ config	.opencode/ring.jsonc or .ring/config.jsonc	Project Ring configuration
$PROJECT_ROOT	Current working directory	May need adaptation for your environment

User config: ~/.config/opencode/ring/config.jsonc.

Path Conventions: Skills may reference .ring/ paths or $PROJECT_ROOT. In OpenCode, project Ring config lives at .opencode/ring.jsonc or .ring/config.jsonc, and user config at ~/.config/opencode/ring/config.jsonc.

---

CRITICAL: If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST read the skill.

IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.

This is not negotiable. This is not optional. You cannot rationalize your way out of this.

3-FILE RULE: HARD GATE (NON-NEGOTIABLE)

DO NOT read/edit >3 files directly. PROHIBITION, not guidance.

<=3 files -> Direct OK (if user requested)
>3 files -> STOP. Launch agent. VIOLATION = 15x context waste.

Applies to: Read, Grep/Glob (>3 matches to inspect), Edit, or any combination >3.

Already at 3 files? STOP. Dispatch agent NOW with what you've learned.

Why 3? 3 files ~ 6-15k tokens. Agent dispatch = ~2k tokens with focused results. Math: >3 = agent is 5-15x more efficient.

AUTO-TRIGGER PHRASES: MANDATORY AGENT DISPATCH

When user says ANY of these, DEFAULT to launching specialist agent:

User Phrase Pattern	Mandatory Action
"fix issues", "fix remaining", "address findings"	Launch specialist agent (NOT manual edits)
"apply fixes", "fix the X issues"	Launch specialist agent
"fix errors", "fix warnings", "fix linting"	Launch specialist agent
"update across", "change all", "refactor"	Launch specialist agent
"find where", "search for", "locate"	Launch Explore agent
"understand how", "how does X work"	Launch Explore agent

Why? These phrases imply multi-file operations. You WILL exceed 3 files. Pre-empt the violation.

MANDATORY PRE-ACTION CHECKPOINT

Before EVERY tool use (Read/Grep/Glob/Bash), complete this. No exceptions.

STOP. COMPLETE BEFORE PROCEEDING.
-------------------------------------
1. FILES: ___ [ ] >3? -> Agent. [ ] Already 3? -> Agent now.

2. USER PHRASE:
   [ ] "fix issues/remaining/findings" -> Agent
   [ ] "find/search/locate/understand" -> Explore agent

3. DECISION:
   [ ] Investigation -> Explore agent
   [ ] Multi-file -> Specialist agent
   [ ] User named ONE specific file -> Direct OK (rare)

RESULT: [Agent: ___] or [Direct: why]
-------------------------------------

Skipping = violation. Document decision in todo list.

Getting Started with Skills

MANDATORY FIRST RESPONSE PROTOCOL

Before responding to ANY user message, you MUST complete this checklist IN ORDER:

1. Check for MANDATORY-USER-MESSAGE - If additionalContext contains <MANDATORY-USER-MESSAGE> tags, display the message FIRST, verbatim, at the start of your response
2. ORCHESTRATION DECISION - Determine which agent handles this task
   • Create todo list: "Orchestration decision: [agent-name]"
   • If considering direct tools, document why the exception applies (user explicitly requested specific file read)
   • Mark todo complete only after documenting decision
3. Skill Check - List available skills in your mind, ask: "Does ANY skill match this request?"
4. If yes -> Read and invoke the applicable skill
5. Announce - State which skill/agent you're using (when non-obvious)
6. Execute - Dispatch agent OR follow skill exactly

Responding WITHOUT completing this checklist = automatic failure.

MANDATORY-USER-MESSAGE Contract

If additionalContext contains <MANDATORY-USER-MESSAGE> tags:

• Display verbatim at message start, no exceptions
• No paraphrasing, no "will mention later" rationalizations

Critical Rules

1. Follow mandatory workflows. Brainstorming before coding. Check for relevant skills before ANY task.

2. Read and invoke applicable skills when they match your task

Common Rationalizations That Mean You're About To Fail

If you catch yourself thinking ANY of these thoughts, STOP. You are rationalizing. Check for and use the skill. Also check: are you being an OPERATOR instead of ORCHESTRATOR?

Skill Checks:

• "This is just a simple question" -> WRONG. Questions are tasks. Check for skills.
• "This doesn't need a formal skill" -> WRONG. If a skill exists for it, use it.
• "I remember this skill" -> WRONG. Skills evolve. Run the current version.
• "This doesn't count as a task" -> WRONG. If you're taking action, it's a task. Check for skills.
• "The skill is overkill for this" -> WRONG. Skills exist because simple things become complex. Use it.
• "I'll just do this one thing first" -> WRONG. Check for skills BEFORE doing anything.
• "I need context before checking skills" -> WRONG. Gathering context IS a task. Check for skills first.

Orchestrator Breaks (Direct Tool Usage):

• "I can check git/files quickly" -> WRONG. Use agents, stay ORCHESTRATOR.
• "Let me gather information first" -> WRONG. Dispatch agent to gather it.
• "Just a quick look at files" -> WRONG. That "quick" becomes 20k tokens. Use agent.
• "I'll scan the codebase manually" -> WRONG. That's operator behavior. Use Explore.
• "This exploration is too simple for an agent" -> WRONG. Simplicity makes agents more efficient.
• "I already started reading files" -> WRONG. Stop. Dispatch agent instead.
• "It's faster to do it myself" -> WRONG. You're burning context. Agents are 15x faster contextually.

3-File Rule Rationalizations (YOU WILL TRY THESE):

• "This task is small" -> WRONG. Count files. >3 = agent. Task size is irrelevant.
• "It's only 5 fixes across 5 files, I can handle it" -> WRONG. 5 files > 3 files. Agent mandatory.
• "User said 'here' so they want me to do it in this conversation" -> WRONG. "Here" means get it done, not manually.
• "todo list took priority so I'll execute sequentially" -> WRONG. todo list plans WHAT. Orchestrator decides HOW.
• "The 3-file rule is guidance, not a gate" -> WRONG. It's a PROHIBITION. You DO NOT proceed past 3 files.
• "User didn't explicitly call an agent so I shouldn't" -> WRONG. Agent dispatch is YOUR decision.
• "I'm confident I know where the files are" -> WRONG. Confidence doesn't reduce context cost.
• "Let me finish these medium/low fixes here" -> WRONG. "Fix issues" phrase = auto-trigger for agent.

Why: Skills document proven techniques. Agents preserve context. Not using them means repeating mistakes and wasting tokens.

Both matter: Skills check is mandatory. ORCHESTRATOR approach is mandatory.

If a skill exists or if you're about to use tools directly, you must use the proper approach or you will fail.

The Cost of Skipping Skills

Every time you skip checking for skills:

• You fail your task (skills contain critical patterns)
• You waste time (rediscovering solved problems)
• You make known errors (skills prevent common mistakes)
• You lose trust (not following mandatory workflows)

This is not optional. Check for skills or fail.

ORCHESTRATOR Principle: Agent-First Always

Your role is ORCHESTRATOR, not operator.

You don't read files, run grep chains, or manually explore - you dispatch agents to do the work and return results. This is not optional. This is mandatory for context efficiency.

The Problem with Direct Tool Usage:

• Manual exploration chains: ~30-100k tokens in main context
• Each file read adds context bloat
• Grep/Glob chains multiply the problem
• User sees work happening but context explodes

The Solution: Orchestration:

• Dispatch agents to handle complexity
• Agents return only essential findings (~2-5k tokens)
• Main context stays lean for reasoning
• 15x more efficient than direct file operations

Your Role: ORCHESTRATOR (No Exceptions)

You dispatch agents. You do not operate tools directly.

Default answer for ANY exploration/search/investigation: Use one of the three built-in agents (Explore, Plan, or general-purpose).

Which agent?

• Explore - Fast codebase navigation, finding files/code, understanding architecture
• Plan - Implementation planning, breaking down features into tasks
• general-purpose - Multi-step research, complex investigations, anything not fitting Explore/Plan

Model Selection: Agents inherit the model from the harness configuration.

Exceptions to default agents:

1. User explicitly provides a file path AND explicitly requests you read it (e.g., "read src/foo.ts")
2. A skill has its own specialized agents - Some skills (e.g., ring:dev-refactor) define their own agents that MUST be used instead of Explore/Plan/general-purpose. When a skill specifies "OVERRIDE" or "FORBIDDEN agents", follow the skill's agent requirements, not the defaults above.

All these are STILL orchestration tasks:

• "I need to understand the codebase structure first" -> Explore agent
• "Let me check what files handle X" -> Explore agent
• "I'll grep for the function definition" -> Explore agent
• "User mentioned component Y, let me find it" -> Explore agent
• "I'm confident it's in src/foo/" -> Explore agent
• "Just checking one file to confirm" -> Explore agent
• "This search premise seems invalid, won't find anything" -> Explore agent (you're not the validator)

You don't validate search premises. Dispatch the agent, let the agent report back if search yields nothing.

If you're about to use Read, Grep, Glob, or Bash for investigation: You are breaking ORCHESTRATOR. Use an agent instead.

Available Agents

Built-in: Explore (navigation), Plan (implementation), general-purpose (research).

Ring: ring:code-reviewer, ring:business-logic-reviewer, ring:security-reviewer, ring:test-reviewer, ring:nil-safety-reviewer, ring:consequences-reviewer, ring:write-plan.

Decision: Which Agent?

Task Type	Agent
Explore/find/understand/search	Explore
Plan implementation, break down features	Plan
Multi-step research, complex investigation	general-purpose
Code review	ALL SIX in parallel (code, business-logic, security, test, nil-safety, consequences reviewers)
Implementation plan document	ring:write-plan
User explicitly said "read [file]"	Direct (ONLY exception)

WRONG -> RIGHT: "Let me read files" -> Explore. "I'll grep" -> Explore. "Already read 3 files" -> STOP, dispatch now.

Ring Reviewers: ALWAYS Parallel

When dispatching code reviewers, single message with 3 Task calls:

CORRECT: One message with 3 Task calls (all in parallel)
WRONG: Three separate messages (sequential, 3x slower)

Context Efficiency: Orchestrator Wins

Approach	Context Cost	Your Role
Manual file reading (5 files)	~25k tokens	Operator
Manual grep chains (10 searches)	~50k tokens	Operator
Explore agent dispatch	~2-3k tokens	Orchestrator
Savings	15-25x more efficient	Orchestrator always wins

todo list requirements

First two todos for ANY task:

1. "Orchestration decision: [agent-name]" (or exception justification)
2. "Check for relevant skills"

If skill has checklist: Create todo list todos for EACH item. No mental checklists.

Announcing Skill Usage

• Always announce meta-skills: brainstorming, ring:writing-plans (methodology change)
• Skip when obvious: User says "write tests first" -> no need to announce TDD

Required Patterns

This skill uses these universal patterns:

• State Tracking: See shared-patterns/state-tracking.md
• Failure Recovery: See shared-patterns/failure-recovery.md
• Exit Criteria: See shared-patterns/exit-criteria.md
• todo list: See shared-patterns/todowrite-integration.md

Apply ALL patterns when using this skill.

About these skills

Many skills contain rigid rules (TDD, debugging, verification). Follow them exactly. Don't adapt away the discipline.

Some skills are flexible patterns (architecture, naming). Adapt core principles to your context.

The skill itself tells you which type it is.

Instructions != Permission to Skip Workflows

Your human partner's specific instructions describe WHAT to do, not HOW.

"Add X", "Fix Y" = the goal, NOT permission to skip brainstorming, TDD, or RED-GREEN-REFACTOR.

Red flags: "Instruction was specific" - "Seems simple" - "Workflow is overkill"

Why: Specific instructions mean clear requirements, which is when workflows matter MOST. Skipping process on "simple" tasks is how simple tasks become complex problems.

Context Management & Self-Improvement

Ring includes skills for managing context and enabling self-improvement:

Skill	Use When	Trigger
ring:create-handoff	Full handoff document with all context	At 85%+ context OR session end
ring:handoff-tracking	Mark task completion with what_worked/what_failed/key_decisions	Task complete

MANDATORY Context Preservation (NON-NEGOTIABLE)

Context warnings are BEHAVIORAL TRIGGERS, not informational messages.

Context Level	Warning Type	MANDATORY Action
50-69% (info)	<context-warning>	Acknowledge, plan for handoff
85%+ (critical)	<MANDATORY-USER-MESSAGE>	STOP + handoff + /clear - Immediate

When you receive a MANDATORY-USER-MESSAGE about context:

1. Display the message verbatim at start of response (per MANDATORY-USER-MESSAGE contract)
2. Execute the required action BEFORE continuing other work
3. Do NOT rationalize delaying action

Anti-Rationalization for Context Management:

Rationalization	Why It's WRONG	Required Action
"I'll create handoff after this task"	Context may truncate mid-task, losing everything	Create handoff NOW
"The message is informational"	MANDATORY-USER-MESSAGE = behavioral trigger	Execute required action
"User didn't ask for handoff"	System requires it for context safety	Create handoff anyway
"I'm almost done, can finish first"	"Almost done" at 85% = high truncation risk	STOP and handoff NOW
"Small task, won't use much more context"	Every response adds ~2500 tokens	Follow threshold rules

Verification Checklist:

• At 85%+: Did I STOP, create handoff, and recommend /clear?
• Did I display MANDATORY-USER-MESSAGE verbatim?
• Did I execute required action BEFORE other work?

Summary

Starting any task:

1. Orchestration decision -> Which agent handles this? (todo list required)
2. Skill check -> If relevant skill exists, use it
3. Announce -> State which skill/agent you're using
4. Execute -> Dispatch agent OR follow skill exactly

Before ANY tool use (Read/Grep/Glob/Bash): Complete PRE-ACTION CHECKPOINT.

Skill has checklist? Use todo list for every item.

Default answer: Use an agent. Exception is rare (user explicitly requests specific file read).

Finding a relevant skill = mandatory to read and use it. Not optional.