shynlee04/hivemind-plugin/hf-l2-meta-builder-core

meta-builder

Overview

Routes requests about OpenCode meta-concepts (skills, agents, commands, tools) to the right specialist. Receives intent → classifies → navigates step-by-step → reports back. Does NOT create, edit, or execute domain work.

When to load this skill: The user wants to create, audit, stack, or configure any OpenCode meta-concept but hasn't gone directly to the specialist. This skill figures out what they need and routes them.

When NOT to load this skill: The user's request already matches a specialist skill directly (e.g., they said "audit this skill" and use-authoring-skills is available). Route directly instead.

What This Skill Handles

What This Skill Does NOT Handle

The Subject Matter

Meta-concepts are the building blocks of an OpenCode project. Skills teach expertise. Agents execute. Commands force action. Tools interact with the environment. This skill teaches agents how to create, audit, stack, and manage those building blocks effectively.

Principles

• Iterative few-step interactive — one step, validate, show user, confirm, proceed. NOT autonomous long-horizon execution.
• No direct execution — route to specialists. Never create skills/agents/commands yourself.
• Max 3 skills per stack — context window is shared. If you can't explain why each skill is needed in one sentence, don't load it.
• Standalone-first — every meta-concept works with OpenCode alone. HiveMind runtime is bonus, not required.
• Edit in labs, test via symlinks — source of truth is .hivefiver-meta-builder/**-lab/. .opencode/ is a symlink for live testing. Never edit .opencode/ directly.

On Load

1. Load background skill per the conditional table below — NOT all of them.

1. Read planning files if they exist: task_plan.md, findings.md, progress.md.

1. For skill stacking (max 3 per stack), MANDATORY — read references/04-skills-chaining.md for loading order and composition rules.

1. Understand the Hivefiver workspace:

The Iron Law

NO STACK WITHOUT A REASON

Max 3 skills per stack. If you can't explain why each skill is needed in one sentence, don't load it. Context window is shared — every unnecessary skill dilutes the ones that matter.

What Agents Actually Rationalize

OpenCode Meta Concepts — Mind Map

Skills teach expertise. Agents execute. Commands force action. Tools interact with the environment. Workflows sequence steps. Permissions gate access. Rules constrain behavior. Configs wire it all together.

Key relationships:

• Skills are loaded by agents via the skill tool — progressive disclosure in action
• Commands bind to agents via agent: frontmatter — deterministic entry points
• Tools are invoked by agents during execution — bash, read, write, grep, glob, etc.
• Workflows are procedural files that agents execute step-by-step
• Permissions (in opencode.json) gate which tools each agent can use
• Rules (in .opencode/rules/) constrain agent behavior globally

Example: An Agentic Workflow in Action

User: "Create a skill for deep research"
  ↓
Command: /hf-create skill=deep-research
  ↓
Agent: hivefiver-orchestrator loads meta-builder skill
  ↓
meta-builder routes to: use-authoring-skills (hivefiver-skill-author)
  ↓
Step 1: Write frontmatter → validate-skill.sh → show user → confirm
  ↓
Step 2: Write body → validate-skill.sh → show user → confirm
  ↓
Step 3: Create references/ → check-overlaps.sh → show user → confirm
  ↓
Step 4: Critic subagent review → fix issues → final validate → commit
  ↓
Result: Skill at .hivefiver-meta-builder/skills-lab/active/refactoring/deep-research/
        Symlinked to .opencode/skills/deep-research/ for live testing

Domain Routing — When to Create What

Power Tools — Built-in Capabilities Often Misused

These OpenCode built-in tools are the most powerful primitives for meta-builder work. Know them. Use them correctly. Reference their depth-skill files when needed.

question — Gate Execution Before Acting

What it does: Presents structured choices to the user during execution. Each question has a header, text, and options. Users can select or type custom answers.

Why it matters: Setting question: allow in agent permissions prevents execution before user approval. The agent MUST stop and ask. This is the primary guardrail against autonomous long-horizon execution.

{
  "permission": {
    "question": "allow",
    "edit": "ask",
    "bash": "ask"
  }
}

When to use: Before routing to a specialist, before committing changes, before loading skills beyond the max-3 limit.

todowrite — Track Progress Visibly

What it does: Creates and updates task lists during complex operations.

Why it matters: Every meta-concept workflow ends with a TODO list showing completion status. This is Step 5 of the 5-step workflow.

- [ ] Frontmatter written and validated
- [ ] Body content complete
- [ ] References created
- [ ] Validation loop passed
- [ ] Committed to git

Note: Disabled for subagents by default. Enable manually when needed.

patch — Apply Diffs Safely

What it does: Applies patch files to your codebase. Controlled by the edit permission (along with edit, write, multiedit).

Why it matters: When auditing and fixing skills across multiple files, patches are safer than full rewrites. They show exactly what changed.

When to use: Applying critic review fixes, syncing lab changes to .opencode/ copies, updating frontmatter across multiple skills.

grep + glob — Find Before You Read

What they do: grep searches file contents with regex. glob finds files by pattern. Both use ripgrep under the hood, respecting .gitignore.

Why it matters: Never read full files when frontmatter or specific sections are needed. Grep first, read only what's necessary.

# Find all skills with missing trigger phrases
grep -r "description:" .opencode/skills/*/SKILL.md | grep -v "Use when"
 
# Find all agent definitions with task: ask
grep -r '"task"' .opencode/agents/*.md

lsp (experimental) — Code Intelligence

What it does: Interacts with LSP servers for definitions, references, hover info, call hierarchy. Requires OPENCODE_EXPERIMENTAL_LSP_TOOL=true.

Why it matters: When auditing TypeScript harness code (src/), use LSP to find all references to a function, trace imports, understand dependencies without reading every file.

skill — Load Skills On Demand

What it does: Loads a SKILL.md file and returns its content in the conversation. This IS the routing mechanism.

Why it matters: When meta-builder routes to use-authoring-skills, it calls skill({ name: "use-authoring-skills" }). This is progressive disclosure in action.

execute-slash-command — Dispatch Commands Deterministically

What it does: Executes an OpenCode slash command via POST /session/:id/command

Why it matters: Commands force action without reasoning overhead

When to use: Running /hf-create, /hf-audit, /hf-stack, or any registered command

hivemind-command-engine — Discover and Analyze Commands

What it does: CQRS read-side for command management. Actions: discover, list_commands, analyze_contract, render_context, transform_messages, route_preview

Why it matters: Don't hardcode command names — discover available commands dynamically before executing.

webfetch + websearch — External Knowledge

What they do: webfetch retrieves content from a specific URL. websearch searches the web via Exa AI.