igorwarzocha__opencode-workflows/agents/README.md

# Opencode Agent Templates

A focused catalog of agent prompts and orchestration patterns designed for Opencode projects. Each agent lives in a `.opencode/agent/` directory with YAML metadata plus a purpose-built instruction block tailored to the workflows it supports.

All agent files use **RFC 2119 keywords** (MUST, SHOULD, MAY) and **XML tags** (`<instructions>`, `<workflow>`, `<rules>`) for precise, unambiguous behavior. See `RFC-XML-STYLE-GUIDE.md` in the repository root for the full specification.

## Architecture Overview

The `agents/` directory contains specialized agent collections. To optimize model usage, **MUST** disable the generic `general` subagent in favor of the `fast`/`smart` split in your `opencode.json`:

```json
"subagents": {
  "general": {
    "disable": true
  }
}
```

- **generic/** – Canonical, globally useful agents that pair well with any Opencode repo. Install these into `~/.config/opencode/agent/` to make them universally available.
- **parallel-PRD/** – Parallel PRD planners plus an orchestrator and PRD authoring skill for best-of synthesis.
- **vite-react-ts-convex-tailwind/** – A stack-specific toolkit that bundles six specialists plus stack documentation files (`CONVEX.md`, `REACT19.md`, `TAILWIND4.md`, `TS59.MD`, `CODING-TS.md`). Each expert agent explicitly references its matching doc so it can cite authoritative guidance when reasoning.

Each collection demonstrates how to scope agents for a domain, define guardrails in YAML frontmatter, and ship reusable workflows alongside optional documentation.

## Agent Collections

### Generic Global Agents (`agents/generic/.opencode/agent/`)

| Agent | Description |
| --- | --- |
| `fast` | High-speed workhorse. Use for trivial edits, running known commands, and simple file lookups. Part of the `fast`/`smart` split to replace the generic `general` agent. |
| `smart` | Senior developer and architect. Use for complex bug hunting, codebase refactoring, and verified implementation. Part of the `fast`/`smart` split to replace the generic `general` agent. |
| `repo-navigator-creator` | Produces lean AGENTS.md navigation guides so LLMs can traverse repositories without context overload. |
| `subagent-orchestrator` | Dispatches specialized agents, partitions scopes, and manages parallel/sequential execution plans. |
| `openspec-orchestrator` | Enforces strict OpenSpec formatting, runs validations, and coordinates specialists across proposal, implementation, and archive workflows. Requires [OpenSpec](https://openspec.dev/) plus `openspec init`. |

Install these globally whenever you want standard orchestration helpers available in every session.

### Repo Navigator Pack (`agents/repo-navigator/`)

| Component | Description |
| --- | --- |
| `agent/repo-navigator.md` | Primary agent for repository documentation. Whitelists 3 skills for controlled workflows. |
| `command/init.md` | Unified command with argument routing: no arg = full, `basic` = minimal, `user` = user assistance. |
| `skill/agent-navigation-sop/` | AI navigation SOP: build/test commands, coding conventions, task routing. |
| `skill/user-onboarding-sop/` | User assistance SOP: setup, installation, troubleshooting with web search for official docs. |
| `skill/skill-creator/` | Bundled for creating custom skills during full workflow. |

See `agents/repo-navigator/README.md` for workflow diagrams and installation instructions.

### Parallel PRD Pack (`agents/parallel-PRD/.opencode/agent/`)

| Agent | Description |
| --- | --- |
| `parallel-prd-orchestrator` | Primary orchestrator that dispatches planners and writes `/prd/[feat][final].md`. |
| `gemini-pro-planner` | Planner subagent for PRD generation. |
| `glm-planner` | Planner subagent for PRD generation. |
| `gemini-flash-planner` | Planner subagent for PRD generation. |

### Vite + React + TS + Tailwind + Convex Pack (`agents/vite-react-ts-convex-tailwind/.opencode/agent/`)

| Agent | Description |
| --- | --- |
| `VRTCT-orchestrator` | Master coordinator for the full stack, orchestrating subagents and enforcing React 19.2, Tailwind 4.1, TS 5.9, and Convex best practices. Does not write code. |
| `VRTCT-brain` | Stack knowledge base and implementation lead. Writes code grounded in the stack documentation. |
| `convex-database-expert` | Senior Convex engineer covering schema design, queries/mutations/actions, auth, and operational debugging with references to `CONVEX.md`. |
| `react-19-master` | Deep React 19.2 mentor specializing in Server Components, Server Actions, and new compiler-driven ergonomics, grounded in `REACT19.md`. |
| `tailwind-41-architect` | Tailwind CSS 4.1 strategist that pushes the CSS-first architecture, container queries, and modern utility set, citing `TAILWIND4.md`. |
| `typescript-59-engineer` | Strict TypeScript 5.9 expert who enforces erasable syntax, verbatim module imports, and compiler-aligned patterns informed by `TS59.MD`. |

Each specialist is pre-configured with relevant stack documentation and specialized skills (where applicable) to ensure answers stay aligned with the stack standards.

## Usage Flow

1. Identify the collection that matches your context (Generic vs. stack-specific).
2. Reference the relevant agent file in `.opencode/agent/` and review its YAML frontmatter for `mode`, guardrails, and tool constraints.
3. Follow the instruction block exactly—these steps are tuned for autonomous execution.
4. When using stack-specific experts, open the accompanying doc (`CONVEX.md`, etc.) if you need deeper citations or confirmation.
5. Reference `@coding-ts` (`at/CODING-TS.MD`) for universal engineering standards and clean architecture principles.

## Scoped Skills and Isolation

> [!IMPORTANT]
> To ensure predictable behavior and prevent context pollution, agents in this repository follow the **Principle of Least Privilege**. Every agent MUST have irrelevant skills disabled, only enabling the specific skills required for its specialized domain.
>
> Specialized packs (like **VRTCT**) come with pre-configured, scoped permissions. For example, the `convex-database-expert` ONLY allows `convex-*` skills, while others remain strictly denied. Refer to each agent's YAML frontmatter and the pack's `README.md` for specific permission mappings.

## Relationship to Commands

Agents complement Opencode commands:

- **Commands** in `.opencode/command/` describe end-to-end workflows (see `commands2skills/README.md`).
- **Agents** in `.opencode/agent/` provide targeted reasoning, research, or orchestration within those workflows.

Mix and match as needed: commands launch processes, agents keep the reasoning sharp.

## File Structure

```
.
├── at/                      # Global standards (@coding-ts)
└── agents/
    ├── README.md
    ├── generic/
    │   └── .opencode/
    │       └── agent/
    │           ├── fast.md
    │           ├── smart.md
    │           ├── repo-navigator-creator.md
    │           ├── subagent-orchestrator.md
    │           └── openspec-orchestrator.md
    ├── repo-navigator/
    │   ├── README.md
    │   ├── agent/
    │   │   └── repo-navigator.md
    │   ├── command/
    │   │   └── init.md
    │   └── skill/
    │       ├── agent-navigation-sop/
    │       │   └── SKILL.md
    │       ├── user-onboarding-sop/
    │       │   └── SKILL.md
    │       └── skill-creator/
    │           ├── SKILL.md
    │           └── references/
    ├── parallel-PRD/
    │   └── .opencode/
    │       ├── agent/
    │       │   ├── parallel-prd-orchestrator.md
    │       │   ├── gemini-pro-planner.md
    │       │   ├── glm-planner.md
    │       │   ├── gemini-flash-planner.md
    │       │   └── TEMPLATE-planner.md
    │       ├── command/
    │       │   └── parallel-prd.md
    │       └── skill/
    │           └── prd-authoring/
    │               ├── SKILL.md
    │               └── references/
    │                   └── examples.md
    └── vite-react-ts-convex-tailwind/
        ├── CODING-TS.md
        ├── CONVEX.md
        ├── REACT19.md
        ├── TAILWIND4.md
        ├── TS59.MD
        └── .opencode/
            ├── agent/
            │   ├── VRTCT-orchestrator.md
            │   ├── VRTCT-brain.md
            │   ├── convex-database-expert.md
            │   ├── react-19-master.md
            │   ├── tailwind-41-architect.md
            │   └── typescript-59-engineer.md
            └── skill/
                ├── component-engineering/
                ├── convex-auth/
                ├── convex-components/
                ├── convex-core/
                ├── convex-deploy/
                └── convex-runtime/
```

## Adding New Agents

1. Run `opencode agent create` (or copy an existing pattern) to scaffold proper identifiers and mode/tool constraints.
2. Place the file inside the relevant collection’s `.opencode/agent/` directory.
3. Keep instructions lean: highlight guardrails, workflows, and required reference docs.
4. Update this README’s tables/tree so other contributors know the new agent exists.

## Guidance for LLMs

- Always read the agent’s frontmatter before acting; it defines when to use the agent and any tool restrictions.
- Respect documentation hooks—if the agent mentions a supporting `.MD` file, treat it as available context for authoritative answers.
- Ask clarifying questions when requirements are ambiguous rather than guessing.
- Keep responses concise, implementation-focused, and grounded in the referenced standards (@coding-ts, OpenSpec, React 19, Tailwind 4.1, Convex, etc.).