hf-l2-meta-builder

Files (27)

• graph.json · .meta-builder/
• checkpoint.json · .meta-builder/state/
• question-count.json · .meta-builder/state/
• session-stack.json · .meta-builder/state/
• SKILL.md
• agent-frontmatter.md · assets/
• command-frontmatter.md · assets/
• skill-frontmatter.md · assets/
• evals.json · evals/
• trigger-queries.json · evals/
• 01-mindsnetwork-graph.md · references/
• 02-deterministic-control.md · references/
• 03-long-horizon-persistence.md · references/
• 04-skills-chaining.md · references/
• depth-built-in-tools.md · references/
• depth-github-stacks.md · references/
• depth-repo-analysis.md · references/
• depth-skill-synthesis.md · references/
• graph-init.sh · scripts/
• graph-traverse.sh · scripts/
• register-skill.sh · scripts/
• route-check.sh · scripts/
• state-persist.sh · scripts/
• validate-graph.sh · scripts/
• agent-creation-flow.md · workflows/
• command-creation-flow.md · workflows/
• skill-creation-flow.md · workflows/

SKILL.md (first lines)

# 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

| Concept | What Gets Produced (per agentskills.io spec) | Where It Lives |
|---------|---------------------------------------------|----------------|
| **Skills** | `SKILL.md` (required) + `scripts/` (optional) + `references/` (optional) + `assets/` (optional) | `.hivefiver-meta-builder/skills-lab/` → symlinked to `.opencode/skills/` |
| **Agents** | `.md` with YAML frontmatter, permissions, execution flows | `.hivefiver-meta-builder/agents-lab/` → symlinked to `.opencode/agents/` |
| **Commands** | Thin shells with `$ARGUMENTS` parsing, agent binding, CI=true safety | `.hivefiver-meta-builder/commands-lab/` → symlinked to `.opencode/commands/` |
| **Tools** | Zod schema designs, plugin hook patterns, lifecycle management | `.opencode/` config + `src/lib/` for custom tools |

### What This Skill Does NOT Handle

| Not This Skill | Route To Instead |
|----------------|-----------------|
| "Build a NextJS app" / "Add an API endpoint" | Project-building agents (Hiveminder lineage) |
| "Fix a TypeScript bug in src/" | Builder or critic agents |
| "Run the test suite" | Direct execution — no routing needed |
| "Explain how React hooks work" | Web search or direct answer |

## 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.

   | If user asks about... | Load this ONE skill |
   |----------------------|---------------------|
   | Agents, commands, tools, permissions | `opencode-platform-reference` |
   | Codebase analysis, repo exploration | `repomix-exploration-guide` |
   | Shell safety, non-interactive execution | `opencode-non-interactive-shell` |
   | Ambiguous intent, unclear scope | `user-intent-interactive-loop` |
   | Multi-step planning needed | `hm-planning-persistence` |
   | Nothing specific yet | None — wait for routing decision |

2. **Read planning files if they exist:** `task_plan.md`, `findings.md`, `progress.md`.

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

4. **Understand the Hivefiver workspace:**

   | File | Why It Matters |
   |------|---------------|
   | `.hivefiver-meta-builder/AGENTS.md` | Agent team, delegation protocol, iron laws |
   | `.hivefiver-meta-builder/distinguish-hivefiver-meta-builder.md` | Entity boundaries (OpenCode / HiveMind / Hivefiver / Hiveminder) |
   | `.hivefiver-meta-builder/GENERAL-KNOWLEDGE.md` | Platform synthesis requirements, skill lineages |
   | `.hivefiver-meta-builder/ONBOARDING-WORKFLOW-PROTOCOL.md` | Onboarding protocol, skill stack, routing tree |
   | `.hivefiver-meta-builder/SKILLS-AGENTS-COMMANDS-TOOLS.md` | Core lexicon, execution dynamics |
   | `.hivefiver-meta-builder/updating-for-hivefiver-onboarding.md` | Misconceptions, prevention mechanisms |
   | `.hivefiver-meta-builder/workflows-lab/active/refactoring/` | Workflow source of truth |

## 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

| What agents say | What they actually did | Reality |
|-----------------|----------------------|---------|
| "I'll load all the skills to be thorough" | Loaded 6+ skills, context blown, ignored all of them | Max 3. Load order matters. |
| "The routing table says route to X, but I think Y is better" | Routed to wrong skill, task failed | Trust the table. If it's wrong, fix the table — don't improvise. |
| "I can handle this myself, no need to delegate" | Edited files directly, broke patterns | meta-builder routes. It doesn't execute. |
| "I'll just edit the skill file directly" | Created skill that doesn't trigger | Delegate to skill-authoring. Always. |
| "I'll load find-skills to find similar skills first" | Spent context budget on vague self-referential search | Never use find-skills as a pre-creation rabbit hole. |
| "I'll read all 20 skill files at once for the audit" | Blew context, produced unusable report | Chunk audits. One phase at a time. |

## 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
  ↓

From shynlee04/hivemind-plugin, MIT.

More from shynlee04/hivemind-plugin