npm package: @nasr-shaer/agent-forge
Description: Modular block-based agent/subagent definition system for OpenCode
Latest version: 1.1.0

# Agent Forge - OpenCode Plugin

**Modular block-based agent/subagent definition system for OpenCode**

Create custom AI agents using simple Markdown files with optional, composable building blocks.

## Installation

```bash
bun add @nasr-shaer/agent-forge
```

Or add to your `.opencode/config.yaml`:

```yaml
plugin:
  - "@nasr-shaer/agent-forge"
```

Restart OpenCode after installation.

## Quick Start

### 1. Create your first agent interactively

```bash
/forge forge-creator
```

The interactive creator will guide you through:
- Choosing a name and description
- Selecting which blocks to include
- Configuring each block
- Saving the agent to `.opencode/agents/`

### 2. Use your agent

```bash
/forge <your-agent-name>
```

### 3. List available agents

```bash
/forge
```

### 4. Reload agents (after creating new ones)

```bash
/forge --reload
```

Newly created agents are automatically discovered without restarting OpenCode!

## Available Blocks

All blocks are **optional and composable**. Pick only what you need:

| Block | Purpose |
|-------|---------|
| **Variables** | Session-scoped key-value state |
| **Parameters** | Typed inputs with hints, validation, and defaults |
| **Workflow** | Numbered step-by-step execution plan |
| **Report** | Output format and structure definition |
| **Delegation** | Rules for delegating to other agents |
| **Examples** | Code/usage examples |
| **Codebase Structure** | File scanning paths and conventions |
| **Expertise** | Role, domains, knowledge, tone |
| **Guards** | Pre/post conditions, invariants, error handling |
| **Git Consideration** | Commit style, branch strategy, rules |

## Manual Agent Creation

Create a file in `.opencode/agents/my-agent.md`:

```markdown
---
description: What this agent does
mode: primary
blocks:
  - expertise
  - workflow
  - parameters
---

## Expertise
role: Your agent's role
domains:
  - Domain 1
  - Domain 2
tone: Helpful and professional

## Workflow
1. Step one
2. Step two
3. Step three

## Parameters
- name: input_file
  type: string
  required: true
  hint: "Path to input file"
```

Then activate with `/forge my-agent`.

## Features

- **Hot Reload**: New agents are immediately available - no OpenCode restart needed!
- **Interactive Creation**: Use `forge-creator` to build agents through a guided conversation
- **Typed Parameters**: Define inputs with type checking, validation, and hints
- **Composable Blocks**: Mix and match only the blocks you need
- **Per-Agent Commands**: Auto-generated shortcuts like `/forge-my-agent`
- **Markdown-Based**: Simple, readable, version-controllable agent definitions
- **Session State**: Variables and parameters scoped to each session
- **OpenCode Native**: Integrates seamlessly with OpenCode's plugin system

## Architecture

The plugin works by:
1. Scanning `.opencode/agents/` and `agents/` for `.md` files at startup
2. Parsing frontmatter and block sections
3. Registering `/forge` command and per-agent shortcuts
4. **Hot-reloading**: Automatically discovering newly created agents via command interception
5. Injecting agent instructions into system prompt when activated
6. Managing session state for variables and parameters

**Hot Reload Mechanism**: The plugin uses OpenCode's `tui.command.execute` hook to intercept `/forge` commands and dynamically reload agents from the filesystem before looking them up in memory. This means agents created during your session are immediately available without restarting OpenCode.

## Examples

### Code Reviewer Agent

```yaml
---
description: Reviews code changes for quality and best practices
mode: primary
blocks:
  - expertise
  - guards
  - workflow
  - git-consideration
---

## Expertise
role: Senior code reviewer
domains:
  - TypeScript
  - React
  - Testing
  
## Workflow
1. Review changed files
2. Check for anti-patterns
3. Suggest improvements
4. Verify tests exist
```

### Documentation Agent

```yaml
---
description: Generates documentation from code
mode: primary
blocks:
  - parameters
  - workflow
  - report
---

## Parameters
- name: target_dir
  type: string
  required: true
  hint: "Directory to document"
  
## Workflow
1. Scan files in target_dir
2. Extract docstrings and comments
3. Generate markdown docs
4. Save to docs/

## Report
format: markdown
structure:
  - Table of contents
  - API reference
  - Examples
```

## Contributing

This plugin follows the architecture of [subtask2](https://github.com/spoons-and-mirrors/subtask2).

## License

Proprietary

## Author

**nasr.shaer** <shaer.nasrallah@gmail.com>

## Links

- npm: [@nasr-shaer/agent-forge](https://www.npmjs.com/package/@nasr-shaer/agent-forge)
- Documentation: Coming soon