OpenCode Workflow Setup

This repository contains a chat-first OpenCode workflow for feature delivery with explicit approval gates and task-by-task implementation.

It is designed to force a consistent sequence:

1. Specs
2. Plan
3. Tasks
4. Implement

The goal is to clarify requirements before coding, validate the design before tasking, and only implement work that has already been approved.

What This Repository Provides

• A primary workflow orchestrator that routes work to the correct stage
• Hidden subagents for Specs, Plan, Tasks, and Implement
• Reusable slash commands for starting or revisiting the workflow
• Builder skills for creating new agents, commands, skills, and tools
• A document loading flow for external library reference caches in ./docs

This repository is configuration-first. Most workflow artifacts stay in chat unless file output is explicitly requested.

Workflow Model

The main entrypoint is the workflow-orchestrator agent. It enforces three approval gates:

• Gate 1: Specs approved
• Gate 2: Plan approved
• Gate 3: Tasks approved

Implementation starts only after Gate 3.

After Tasks are approved, the orchestrator creates one todo item per atomic task and uses that todo list as the source of truth for execution progress.

Commands

/workflow

Start a new workflow or continue the current one in the same thread.

Example:

/workflow Add email OTP login to the existing React auth flow

/workflow-step

Revisit or force a specific stage while still respecting gate prerequisites.

Examples:

/workflow-step specs We also need account lockout after 3 failed OTP attempts
/workflow-step plan Rework this plan to use the existing NestJS auth module
/workflow-step tasks Split task 3 into smaller backend and frontend tasks

/document-loader

Load or reuse cached documentation artifacts for libraries declared in KNOWN-REPOSITORIES.md.

Examples:

/document-loader
/document-loader ./apps/web

Behavior:

• Reads KNOWN-REPOSITORIES.md at the workspace root
• Selects all projects or one exact Path: match
• Resolves and deduplicates GitHub library repositories
• Uses repomix-explorer to create or reuse XML artifacts in ./docs
• Returns a summary of processed libraries, artifact paths, and warnings

If the mapping file is missing, the command returns:

Không tìm thấy KNOWN-REPOSITORIES.md

Skills

Workflow skills

• workflow-contracts: maintenance reference for workflow semantics and handoff rules

Builder skills

• create-agent
• create-command
• create-skill
• create-tool

Reference and discovery skills

• repomix-explorer: creates or reuses repository documentation artifacts in ./docs
• known-repositories-docs: decides when cached docs are relevant and which artifact should be consulted for a task
• nuget-find: repository-local skill for NuGet package discovery

External Library Docs Flow

This repository supports a lightweight documentation cache for external dependencies.

Create a KNOWN-REPOSITORIES.md file at the workspace root with blocks like:

# Project:
Path: ./apps/web
Libraries:
- https://github.com/vercel/next.js
- https://github.com/prisma/prisma

Then run /document-loader to create or reuse artifacts under ./docs.

The known-repositories-docs skill helps the agent decide:

• when external docs are actually needed
• which project block applies to the current task
• which artifact in ./docs should be searched first

This keeps library lookup targeted instead of loading unrelated documentation into context.

Repository Structure

.opencode/
  agents/      Hidden workflow agents
  commands/    Reusable slash commands
  skills/      Project-local OpenCode skills
  tools/       Reserved for project-local custom tools
docs/          Cached Repomix XML artifacts
AGENTS.md      Detailed repository contract and operating rules

OpenCode Configuration

The repository already includes OpenCode configuration under .opencode/ and is ready for custom tool expansion through @opencode-ai/plugin.

Configured integrations currently include:

• context7 MCP
• exa-mcp
• chrome-devtools-mcp
• @knikolov/opencode-plugin-simple-memory

Quick Start

1. Open this repository in OpenCode.
2. Start with /workflow <your request>.
3. Answer the Specs questions.
4. Approve Specs, then Plan, then Tasks.
5. Let the orchestrator manage todo creation and implementation routing.
6. If a task depends on external library behavior, add KNOWN-REPOSITORIES.md and run /document-loader.

Notes

• This workflow is intentionally chat-first.
• Hidden subagents are meant to be invoked by the orchestrator, not used as public entrypoints.
• ./docs is treated as a long-lived cache for external reference artifacts.
• If scope changes after Plan or Tasks approval, downstream work should be revisited instead of patched ad hoc.