opencode-config-workflow

name	opencode-config-workflow
description	Framework-agnostic guided workflow for configuring OpenCode agents, commands, and skills programmatically. Turn-based: Discover → Investigate → Collect → Proposal → Validate → Compile → Test → Save. Supports individual and batch configuration with cross-primitive conflict detection. Coexists safely with GSD, BMAD, Speckit, and other frameworks. Triggers on: 'configure agent', 'configure command', 'configure skill', 'batch configure', 'agent setup', 'set up agent', 'configure OpenCode primitives', 'update agent', 'modify agent', 'change agent', 'batch update', 'reconfigure', 'gatekeeping setup' .
metadata	{"layer":"2","role":"workflow-orchestration","pattern":"P1-procedural","depends_on_tools":["configure-primitive","validate-restart"],"depends_on_libs":["cross-primitive-validator","config-compiler","schema-kernel","framework-detector","runtime-validator"]}

Overview

This skill guides agents through an 8-turn configuration workflow for OpenCode primitives (agents, commands, skills). It does NOT create files directly — it orchestrates the process and delegates to tools.

Works safely alongside GSD (.planning/), BMAD (bmad.yaml), Speckit (speckit.json), and any other framework by detecting their boundaries and namespace-tagging generated configs.

The Iron Law

NO DIRECT FILE CREATION — USE configure-primitive TOOL

1. Workflow enforcement: Pass workflowTurn and workflowId on every configure-primitive call. The tool rejects out-of-order turns.
2. State persistence: Workflow state is automatically persisted to disk. It survives context resets and session interruptions.
3. Resume capability: Use action: "resume" with workflowId to recover state after interruption.

🔨 IRON CLAW: Tech-Stack References & Assets Consumption Governance

ABSOLUTE RULE: No bundled reference, cached asset, or stale pattern from this skill shall be consumed for tech-stack API interface decisions without MCP-verified validation against the project's ACTUAL versions (package.json + lockfile), canonical source mappings (.hivemind/STACKS-REFERENCES.md), AND a raw codebase context scan of the current implementation state.

Rationale

Skills bundle references and assets as ORIENTATION tools — they help you understand WHAT exists and WHERE to look. But every bundled reference is a SNAPSHOT, frozen at the moment of ingestion. Stacks evolve: packages release breaking changes, APIs shift, SDKs deprecate surfaces. Using stale bundled signatures as implementation authority produces silent runtime errors.

Mandatory 5-Step Validation Chain

Before ANY tech-stack API interface from this skill's references/assets is used for implementation, code generation, or quality gate decisions:

STEP 1 — CONSUME .hivemind/STACKS-REFERENCES.md
 ├─ Read the canonical stack→repo→version mapping table
 ├─ Identify the correct GitHub repo for each dependency
 └─ Confirm the repo is active (not archived), version is current

STEP 2 — READ package.json + lockfile
 ├─ Extract the ACTUAL installed version (npm ls / grep lockfile)
 ├─ Cross-reference repo URL from STACKS-REFERENCES.md against npm registry
 └─ Flag any discrepancy between bundled version and installed version

STEP 3 — RAW CODEBASE CONTEXT SCAN
 ├─ grep/glob the actual src/ directory structure for current implementation
 ├─ Read current implementation files — not stale docs or bundled references
 ├─ Verify the claimed API signatures match current codebase reality
 └─ Check import paths, type definitions, and function signatures exist in actual code

STEP 4 — MCP LIVE VALIDATION (minimum 2 tools)
 ├─ Context7: resolve-library-id → query-docs (API signatures at installed version)
 ├─ DeepWiki: ask-question (architecture patterns, behavioral semantics)
 ├─ Repomix: pack-remote-repository (full repo analysis at correct version tag)
 ├─ Exa: web-search (latest docs, tutorials, migration guides)
 ├─ Tavily: search + extract (version-specific migration info)
 ├─ GitHub: get-file-contents (exact source verification at correct version)
 └─ GitMCP: search-code (source-level pattern matching)

STEP 5 — VERIFICATION RECORD
 ├─ Source URL + version confirmed to match package.json
 ├─ MCP tool(s) used + fetch timestamp
 ├─ Codebase scan paths + findings
 ├─ Version match status (MATCHED / MISMATCHED / UNVERIFIED)
 └─ Flag as BLOCKING if version mismatch or critical staleness detected

Consumption Rules

Action	Rule
Orientation (understanding WHAT exists, WHERE to look)	✅ Reference-tier allowed from bundled assets without live validation
API signature lookup for implementation	🚫 BLOCKED without live MCP validation (Step 4) + codebase scan (Step 3)
Interface verification for quality gates	🚫 BLOCKED without live MCP validation (Step 4) + version match (Step 2)
Version-sensitive behavioral claims	🚫 BLOCKED without live MCP validation (Step 4)
Architecture pattern understanding	✅ Reference-tier allowed, but recommend live verification for production decisions
Generating code from bundled patterns	🚫 BLOCKED — route to live MCP tools for current API surface

Integrated Enforcement Points

Workflow Phase	IRON CLAW Trigger	Required Validation
Implementation	Before using any API from bundled refs	Steps 2-4 minimum
Code review	When verifying API usage against docs	Steps 2-4 minimum
Quality gate	Before PASS verdict on interface claims	Steps 1-5 full
Research	When synthesizing findings from cached assets	Steps 4-5 minimum
Audit	When reporting version-based findings	Steps 1-5 full

8-Turn Workflow

Turn 0: Discovery

• Goal: Understand what needs configuration and discover existing resources
• Tool call: configure-primitive(action: "compile", workflowTurn: 0, workflowId: "<id>", ...)
• Actions:
  1. Parse user's request for:
     • Primitive type(s): agents, commands, skills, or all
     • Scope: project (.opencode/) or global (~/.config/opencode/)
     • Mode: create new vs. modify existing vs. batch update
     • Category filters: names, roles (e.g., "gatekeeping", "coordinator", "specialist"), or patterns
  2. Detect co-existing frameworks via framework-detector to avoid boundary conflicts:
     • GSD: .planning/ directory detected → namespace-tag configs with gsd- prefix if needed
     • BMAD: bmad.yaml detected → respect bmad/ boundary
     • Speckit: speckit.json detected → respect speckit/ boundary
  3. If the user mentions a category/role (e.g., "gatekeeping agents", "all coordinators"):
     • Scan .opencode/agents/ for agent .md files
     • Read frontmatter from each to find matching agents by description, mode, or role keywords
     • Present the discovered agents: "I found these gatekeeping agents: [list]. Are these the ones you want to configure?"
  4. If the user provides NO specific names or categories:
     • Ask: "Which specific agents, commands, or skills do you want to configure? I can also scan for agents matching a role like 'gatekeeping' or 'coordinator'."
  5. Determine mode:
     • create — brand new primitive
     • modify — update existing: read current frontmatter, present as starting point
     • batch-modify — update multiple existing: apply same changes to all matched
• Output: { primitives: [...], mode: "create"|"modify"|"batch-modify", scope: "project"|"global", frameworks: [...] }
• Checkpoint: "I found these targets. Proceed with configuration?"

Turn 1: Investigate

• Goal: Understand what the user wants to configure
• Tool call: configure-primitive(action: "compile", workflowTurn: 1, workflowId: "<id>", ...)
• Actions:
  1. If Turn 0 discovered targets and determined mode: Start from Turn 0's output. Show the discovered targets. Do NOT re-ask "what primitive" or "new or modifying" — they're already known.
  2. If modifying or batch-modify: Read existing file(s), extract current frontmatter (decompile)
  3. If no Turn 0 was run (direct Turn 1 entry):
     • Ask: "What primitive are you configuring?" (agent/command/skill)
     • Ask: "Is this a new configuration or modifying an existing one?"
  4. Check for related primitives that might conflict
  5. Check framework boundaries — warn if proposed config would write into a framework-owned directory
• Output: { primitive: "agent"|"command"|"skill", mode: "create"|"modify"|"batch-modify", target?: string | string[] }
• Checkpoint: Present findings, ask "Proceed to collection?"

Turn 2: Collect

• Goal: Gather all required frontmatter fields
• Tool call: configure-primitive(action: "compile", workflowTurn: 2, workflowId: "<id>", ...)
• Actions:
  1. List required fields for the primitive type (from schema-kernel schemas)
  2. For agents: description (required), mode, model, temperature, color, steps, permission, etc.
  3. For commands: description (required), agent, model, subtask, body template
  4. For skills: name (required), description (required), license, compatibility, metadata
  5. Ask user for each field or accept bulk JSON/YAML input
  6. Apply namespace prefix if framework detection indicated potential collisions
• Output: Complete frontmatter object + body content
• Checkpoint: Show collected fields, ask "Proceed to proposal?"

Turn 3: Proposal

• Goal: Present a complete spec for user approval
• Tool call: configure-primitive(action: "compile", workflowTurn: 3, workflowId: "<id>", ...)
• Actions:
  1. Assemble final frontmatter + body into spec object
  2. Run dry-run compilation: configure-primitive(primitive, spec, dryRun: true)
  3. Show the would-be .md content
  4. Show the would-be file path
  5. Highlight any framework boundary implications
• Output: Full spec + preview of compiled .md
• Checkpoint: "Review the above configuration. Approve, modify, or cancel?"

Turn 4: Validate

• Goal: Cross-primitive conflict detection + framework boundary check
• Tool call: configure-primitive(action: "compile", workflowTurn: 4, workflowId: "<id>", ...)
• Actions:
  1. Build PrimitiveMap from BOTH existing locations:
     • Project scope: scan .opencode/agents/, .opencode/commands/, .opencode/skills/, .opencode/tools/, .opencode/plugins/
     • Global scope: scan ~/.config/opencode/ (or process.env.OPENCODE_CONFIG_DIR) with same subdirectory structure
     • Project primitives take precedence over global primitives (same name in both → project wins)
  2. Detect co-existing frameworks and their boundaries
  3. Add the proposed new primitive to the appropriate map
  4. Call validateCrossPrimitive(primitives) — reference the lib function
  5. Call validateRuntime(primitives) to check for circular dependencies, loading order, and pipeline misalignment
  6. If errors (BLOCK severity): report and return to Turn 2 for fixes
  7. If warnings (WARN severity): present to user for accept/override decision
  8. If info: note and proceed
• Output: Validation report (pass/fail + any warnings accepted)
• Checkpoint: If BLOCK → "Fix these issues first." If WARN → "Accept warnings?"

Turn 5: Compile

• Goal: Compile the validated spec to .md format
• Tool call: configure-primitive(action: "compile", workflowTurn: 5, workflowId: "<id>", ...)
• Actions:
  1. Call configure-primitive(primitive, spec, dryRun: false, validate: true)
  2. This writes the .md file to the correct location
  3. Verify the file was written (read it back)
• Output: Written file path + confirmation
• Checkpoint: "File written to {path}. Proceed to testing?"

Batch Modification Mode

When Turn 0 discovers multiple existing primitives and mode is "batch-modify":

1. Read each existing agent's current frontmatter (decompile)
2. Present all current configs side-by-side as a table
3. Ask: "What fields do you want to change across ALL of these agents?"
4. Apply the same changes to all targets:
   • If changing model: update model field on all matched agents
   • If changing temperature: update temperature on all matched agents
   • If changing permissions: update permission on all matched agents
   • If changing instructions: update body content on all matched agents
5. Run dry-run for all targets in batch
6. Compile ALL in atomic batch (all-or-nothing)
7. If any fails validation, roll back ALL

Turn 6: Test

• Goal: Verify the compiled configuration is valid and restart-safe
• Tool call: configure-primitive(action: "compile", workflowTurn: 6, workflowId: "<id>", ...)
• Actions:
  1. Read the written .md file
  2. Run decompile on it — verify frontmatter parses correctly
  3. Check that file path is discoverable by OpenCode (correct directory structure)
  4. Run validate-restart tool to simulate OpenCode discovery and catch runtime issues
  5. Run typecheck if the primitive is a tool AND a tsconfig.json exists in the target directory: npx tsc --noEmit
     • Only run TypeScript typecheck when tsconfig.json is present; skip for non-TypeScript projects
  6. Note: .opencode/rules/ is NOT auto-discovered by OpenCode — rules must be explicitly wired via instructions in opencode.json or agent frontmatter
• Output: Test results (pass/fail)
• Checkpoint: "Tests passed. Save and finalize?"

Turn 7: Save

• Goal: Finalize and report
• Tool call: configure-primitive(action: "compile", workflowTurn: 7, workflowId: "<id>", ...)
• Actions:
  1. Commit the new/modified file to git with descriptive message
  2. Report summary: what was configured, where, and how to verify
  3. Mention any detected frameworks and namespace prefixes applied
• Output: Git commit hash + summary

Batch Mode

When user provides multiple specs at once (JSON array or YAML manifest):

1. Process each spec through Turns 1-4 individually
2. Compile ALL in a single atomic batch in Turn 5
3. If any spec fails validation, roll back ALL (don't write partial batches)
4. Test all in Turn 6, commit all in Turn 7

Resume Protocol

If the workflow is interrupted:

1. Call configure-primitive(action: "resume", workflowId: "<id>") to recover state
2. The tool returns: current turn, completed turns, last output
3. Resume from the returned turn — do NOT re-do completed turns
4. Always pass workflowTurn and workflowId on each configure-primitive call for enforcement

The tool-backed workflow enforces turn order — attempts to skip turns are rejected with a descriptive error.

Anti-Patterns

Anti-Pattern	Detection	Correction
Writing files directly without configure-primitive tool	Did you use Write/Edit instead of configure-primitive?	STOP. Use the tool.
Skipping validation	Did you skip Turn 4?	Always validate before compile.
Accepting BLOCK errors	Did you proceed despite validation BLOCK?	BLOCK means stop. Fix first.
Creating from scratch without investigating existing	Did you skip Turn 1?	Always investigate first.
Ignoring framework boundaries	Did you write into .planning/ or bmad/ without checking?	Use framework-detector first.