StaffForge AI Agent Framework

Multi-provider agent framework. Write agents once, deploy anywhere.

Why StaffForge

If your team uses more than one AI coding assistant — OpenCode, Claude Code, Cursor, GitHub Copilot, Aider, Gemini CLI — you've probably rewritten the same agent rules, prompts, and conventions for each one, and kept rewriting them every time a rule changes.

StaffForge solves that by separating what your agents know from where they run:

• Define an agent once in agents/*.md (Markdown + frontmatter).
• Export it to any supported platform's native format with one command.
• Update the rule in one place; re-export to every platform instead of hand-editing 6 config formats.

StaffForge is not an agent-execution runtime like LangGraph or CrewAI — it doesn't call LLM APIs itself. It's a definition layer and orchestrator/router that sits on top of the AI coding tools you already use, plus a Model Selection Layer for choosing which model a task should use.

Table of contents

• Why StaffForge
• Quick start
• Installation per platform
• Interactive installer
• Agent modes
• Architecture
• Routing
• Prompt examples
• Commands
• Adapting to a new platform
• Model Selection Layer
• Requirements
• Testing
• Project layout
• Documentation
• Contributing
• License
• Support

Project layout

agents/           ← Canonical agent definitions (Markdown + frontmatter)
adapters/         ← Platform-specific exporters (OpenCode, Claude Code, Cursor, etc.)
packages/         ← Monorepo packages (core, sdk, plugin-sdk, cli, dashboard, enterprise)
schemas/          ← JSON Schema for agent validation
templates/        ← Scaffolding for new agents
models/           ← Model definitions and task profiles (Model Selection Layer)
tools/            ← CLI scripts (validate, export, init, install)
tests/            ← Unit, integration, and e2e test suites
examples/         ← Usage examples

Quick start

From any project — one command, all OS

Two equivalent install methods:

A) npm registry (recommended) — no git dependency, EALLOWGIT-safe (works on npm ≥ 11.10 with allow-git=none):

npm exec --yes -- @staffforge/staffforge-ai-agent-framework

B) GitHub direct — installs straight from the repo (may be blocked by npm ≥ 11.10's allow-git policy on some setups):

npm exec --yes -- github:StaffForge/StaffForge-AI-Agent-Framework

Both work on Linux, macOS, and Windows — Node.js ≥ 18 is the only requirement. (If your npm version supports it, you may also use npx @staffforge/staffforge-ai-agent-framework or npx github:StaffForge/....)

Interactive prompts ask for:

• Platform — opencode, claude-code, cursor, copilot, aider, gemini-cli, or all
• Default agent — orchestrator, build, or plan
• Location — project root (default), isolated ./staffforge/, or global (~/.config/staffforge/)
• VCS provider — git, svn, hg, tfvc, perforce, or custom
• Workflow — git-flow, github-flow, gitlab-flow, trunk-based, or custom

After install, config files are placed in your project root (no ./staffforge/ folder is left behind), .claude/agents is a symlink to the canonical agents/ dir, and a .staffforge-install.json is saved so re-running detects previous settings:

# Update to latest agents (detects previous config):
npm exec --yes -- @staffforge/staffforge-ai-agent-framework
# → Previous: opencode (agent: orchestrator)
#   Reinstall? [Y/n]:  ← press Enter

⚠️ npm 9.x note: If npx github:user/repo fails with could not determine executable to run, use npm exec --yes -- github:user/repo instead. Both invoke the same underlying engine; the npm exec form avoids a parsing issue in npm 9.2.0's npx.

Non-interactive with CLI flags

All options can be passed as flags for automation:

# Minimal: OpenCode + orchestrator (defaults for the rest)
npm exec --yes -- @staffforge/staffforge-ai-agent-framework --platform opencode --agent orchestrator

# Full config
npm exec --yes -- @staffforge/staffforge-ai-agent-framework \
  --platform opencode \
  --agent orchestrator \
  --out ./myproject \
  --vcs git \
  --workflow git-flow \
  -y

# Specific platform + agent
npm exec --yes -- @staffforge/staffforge-ai-agent-framework --platform claude-code --agent build

# All platforms at once (files land in project root; agents/ at root; per-platform symlinks)
npm exec --yes -- @staffforge/staffforge-ai-agent-framework --platform all

# All defaults (equivalent to interactive with all defaults)
npm exec --yes -- @staffforge/staffforge-ai-agent-framework -y

# Regenerate existing files (backs up <file>.bak before overwriting)
npm exec --yes -- @staffforge/staffforge-ai-agent-framework --force

CLI reference

| Flag | Description | Values | |------|-------------|--------| | --platform | Target platform | opencode, claude-code, cursor, copilot, aider, gemini-cli, all | | --agent | Default agent mode | orchestrator, build, plan | | --out | Output directory | Any path (default: current directory) | | --vcs | Version control system | git, svn, hg, tfvc, perforce, custom | | --workflow | Workflow preset | git-flow, github-flow, gitlab-flow, trunk-based, custom | | --yes, -y | Skip prompts, use defaults | (flag) | | --help, -h | Show help | (flag) |

Clone the repository (any OS)

git clone --depth 1 https://github.com/StaffForge/StaffForge-AI-Agent-Framework.git
cd StaffForge-AI-Agent-Framework
npm install            # install dependencies — NOTE: no "run"
npm run setup          # interactive installer

⚠️ npm install vs npm run install Use npm install (without run) to install dependencies. npm run install is not a valid command in this project — it fails with Missing script: "install". To run the framework's installer, use npm run setup (or node install.mjs).

OpenCode: setup is one-time + restart required OpenCode reads opencode.json at startup — there is no hot reload. After npm run setup (or npm run auto-init), restart OpenCode so the Orchestrator becomes the default agent. If the Orchestrator is ever missing as default, run npm run auto-init (self-healing: only regenerates when the config is stale) and restart.

Export to other platforms (after cloning)

npm run export:claude      # Claude Code
npm run export:cursor      # Cursor
npm run export:copilot     # GitHub Copilot
npm run export:aider       # Aider
npm run export:gemini      # Gemini CLI

Installation per platform

Export agents to any supported platform:

node tools/export.mjs --platform <name> [--out <dir>]

OpenCode

node tools/export.mjs --platform opencode

| Output | Purpose | |--------|---------| | opencode.json | Agent config (modes, permissions) |

Agents with mode: primary appear in the Tab cycle (orchestrator, build, plan). Agents with mode: subagent appear in the @ autocomplete menu (148 specialized agents).

The installer (v2.7.3+) writes config files directly to the target (project root for single-platform installs) — no adapters/opencode/output/ staging step. Use --out <dir> only to redirect the output elsewhere.

Claude Code

node tools/export.mjs --platform claude-code

| Output | Purpose | |--------|---------| | CLAUDE.md | Orchestrator instructions (top-level rules) | | .claude/agents/<agent>.md | Symlink to canonical agents/ (single source) | | .claude/rules/*.mdc | Always-on rules (no agents dumped here) |

Claude Code reads CLAUDE.md automatically from the project root. The .claude/agents/ folder is a symlink to the canonical agents/ directory (junction on Windows), so subagents stay in sync with the framework source.

Copy the output to your project root:

cp -r adapters/claude-code/output/* .

Cursor

node tools/export.mjs --platform cursor

| Output | Purpose | |--------|---------| | .cursor/rules/<agent>.mdc | One .mdc rule file per agent |

Cursor loads .mdc files from .cursor/rules/ automatically. Each file has frontmatter with a description field so Cursor can select the right rule for the context.

Copy the output to your project root:

cp -r adapters/cursor/output/.cursor .

GitHub Copilot

node tools/export.mjs --platform copilot

Three layers are generated (see AGENTS.md "Copilot Architecture"):

| Output | Purpose | |--------|---------| | .github/copilot-instructions.md | NEUTRAL project context (applyTo: "**") — does NOT embed agent bodies | | .github/agents/*.agent.md | All 150 agents @mention-able, including @orchestrator (full prompt) | | .github/instructions/*.instructions.md | Skills (loaded by file glob) |

How to use: copilot-instructions.md is intentionally neutral because applyTo: "**" applies to every Copilot conversation (including built-in @ask, @plan, @workspace) — embedding the orchestrator would override them. The main agent is @orchestrator: invoke it to run the full multi-agent pipeline; its complete rules load from .github/agents/orchestrator.agent.md. Technology agents (@python, @typescript, @react, etc.) are available via @mention.

Copy the output to your project root:

cp -r adapters/copilot/output/.github .

Aider

node tools/export.mjs --platform aider

| Output | Purpose | |--------|---------| | .aider.rules.md | All agents as rule definitions |

Aider loads .aider.rules.md automatically from the project root. Each agent's full body is included, separated by ---.

Copy the output to your project root:

cp adapters/aider/output/.aider.rules.md .

Gemini CLI

node tools/export.mjs --platform gemini-cli

| Output | Purpose | |--------|---------| | .gemini/<agent>.md | One prompt file per agent |

Gemini CLI reads markdown files from .gemini/ as system prompts. Each file contains the agent's full instructions.

Copy the output to your project root:

cp -r adapters/gemini-cli/output/.gemini .

Interactive installer

node install.mjs

Runs the export for any supported platform and copies the config files to your project. Supports all flags:

node install.mjs --platform opencode --agent orchestrator
node install.mjs --platform claude-code --agent build
node install.mjs --platform all
node install.mjs -y                                 # defaults (opencode, orchestrator, project-local)
node install.mjs --vcs svn --workflow trunk-based   # SVN with trunk-based workflow

The installer asks five questions when run interactively:

1. Platform — which AI coding assistant(s) to target
2. Default agent — orchestrator (full control), build (fast edits), or plan (read-only)
3. Location — project-local (./staffforge/) or global (~/.config/staffforge/)
4. VCS provider — Git, SVN, Mercurial, TFVC, Perforce, or custom
5. Workflow — Git Flow, GitHub Flow, GitLab Flow, Trunk Based, or custom

After selection, the installer:

• Generates platform config files (opencode.json, CLAUDE.md, .cursor/rules/, etc.)
• Copies all 150 agent definitions to agents/
• Creates .staffforge-vcs.json with VCS configuration
• Initializes a Git/Mercurial repository if needed

Agent modes

| Mode | Tab cycle | @ mention | Permissions | |------|-----------|-----------|-------------| | orchestrator | ✓ default | ✓ | Full tools | | build | ✓ | ✓ | Full tools | | plan | ✓ | ✓ | Read-only | | 148 subagents | — | ✓ | Varies |

• Tab — Cycle: orchestrator → build → plan
• @name — Invoke any subagent (e.g., @security, @testing, @ci, @docker, @flask, @react, @postgres)
• Orchestrator is the default agent. It detects task type AND technologies from your prompt, then routes to the right specialist agents.

Architecture

• Orchestrator (default agent) — receives all requests, detects task type and technologies, creates git flow branches, routes pipelines, communicates with the user
• Subagents (148) — specialized roles (language experts, frameworks, databases, infrastructure, testing, security, CI/CD, etc.)
• Only the orchestrator may talk to the user, write files, or manage git
• Subagents run in parallel when they have no dependency on each other (DAG-based execution)

Routing

See ORCHESTRATOR_MATRIX.md for task → pipeline mapping with parallel execution groups.

Prompt examples

The orchestrator detects both the task type and the technologies from your prompt, then invokes the relevant specialist agents. Mention the technologies explicitly for best results:

# Python web — detects flask, sqlalchemy, postgres, pytest
"Add a Flask REST API with SQLAlchemy models for users and products, store in PostgreSQL, cover with pytest tests"

# .NET web — detects aspnet-core, entity-framework, sqlserver, xunit
"Create an ASP.NET Core API with Entity Framework connecting to SQL Server, add xUnit tests"

# Frontend — detects react, typescript, tailwind, vitest
"Build a React dashboard with TypeScript, style with Tailwind, test with Vitest"

# Full stack — detects react, fastapi, postgres, docker
"Implement a todo app: React frontend, FastAPI backend, PostgreSQL database, Docker compose"

# Mobile — detects react-native, typescript
"Fix the login screen in our React Native app written in TypeScript"

# DevOps — detects docker, github-actions, aws
"Set up CI with GitHub Actions to build the Docker image and deploy to AWS ECS"

# Database — detects postgres, redis, sqlalchemy
"Optimize slow queries: Postgres with Redis caching, accessed via SQLAlchemy"

# Mixed Python + .NET — both specialist agents are invoked
"Port the authentication module from Python Flask to ASP.NET Core"

The orchestrator:

1. Detects task type (feature, bugfix, refactor, security, deployment, hotfix)
2. Scans for technology keywords (flask → @flask, react → @react, postgres → @postgres, etc.)
3. Builds a pipeline mixing the base task flow with the detected technology agents
4. Executes in DAG-based parallel levels

Commands

One-line install (any project, no clone needed)

# npm registry (recommended, EALLOWGIT-safe):
npm exec --yes -- @staffforge/staffforge-ai-agent-framework [options]

# GitHub direct (alternative):
npm exec --yes -- github:StaffForge/StaffForge-AI-Agent-Framework [options]

After cloning the repo

# Root-level (npm)
npm install              # Install all dependencies (tools/ included)
npm run setup            # Interactive installer
npm run setup:opencode   # Non-interactive: OpenCode + orchestrator
npm run auto-init        # Self-healing: regenerate opencode.json only if stale (then restart OpenCode)
npm run export:opencode  # Export to OpenCode
npm run export:claude    # Export to Claude Code
npm run export:cursor    # Export to Cursor
npm run export:copilot   # Export to GitHub Copilot
npm run export:aider     # Export to Aider
npm run export:gemini    # Export to Gemini CLI
npm run validate         # Validate all agents
npm test                 # Run all 848+ tests (31 suites)

# Low-level (node)
node install.mjs                          # Interactive installer (any platform)
node install.mjs --platform opencode      # Non-interactive: OpenCode
node install.mjs --platform claude-code   # Non-interactive: Claude Code
node install.mjs --agent orchestrator -y  # Non-interactive with defaults
node tools/export.mjs --platform <name>   # Export agents for any platform
node tools/validate.mjs                   # Validate all agent definitions
node tools/init-agent.mjs <name>          # Create a new agent from template
node tests/run-all.mjs                    # Run test suite

# Environment variables
STAFFFORGE_LOG_LEVEL=debug node tools/export.mjs --platform opencode  # Verbose logging
STAFFFORGE_LOG_LEVEL=error node tools/validate.mjs                    # Errors only

Adapting to a new platform

1. Create adapters/<name>/index.mjs exporting a default function
2. Function receives agents[], returns [{path, content}]
3. Run node tools/export.mjs --platform <name>

opencode.json

Not committed to repo. Generate with node install.mjs, node tools/export.mjs --platform opencode, or npm exec --yes -- @staffforge/staffforge-ai-agent-framework.

Model Selection Layer

The framework includes a Model Selection Layer for optimal model selection:

• 22 model definitions across 6 providers (OpenAI, Anthropic, Google, OpenRouter, Ollama, OpenCode)
• 8 task profiles in models/profiles.yaml mapping task types to preferred model families
• Selection Engine: weighted scoring (profile fit, capabilities, priority, cost, reasoning)
• Fallback Engine: 4-level chain (primary → same-provider → other-provider → free)
• Learning Engine: tracks execution history and adjusts rankings by success rate
• Model Selector facade: 4 strategies (intelligent, cheapest, fastest, free)

Note: This is a pure selection layer — it chooses the optimal model and returns it. It does not invoke LLM APIs directly. The agentFn parameter in FallbackEngine and ModelSelector is provided for callers to supply their own execution logic.

See ARCHITECTURE.md §2 for full API reference.

Requirements

• Node.js ≥ 18 (Linux, macOS, or Windows)
• No other runtime dependency — the installer (npm exec --yes -- @staffforge/staffforge-ai-agent-framework) works standalone
• A supported AI coding assistant already installed for whichever platform(s) you target (OpenCode, Claude Code, Cursor, GitHub Copilot, Aider, or Gemini CLI)

Testing

npm test                 # Run all suites (unit, integration, e2e)
npm run validate         # Validate every agent definition against the JSON Schema
npm run lint             # ESLint over tools/ and packages/
npm run format           # Prettier check

The suite currently covers unit tests (registries, engines, DAG, scheduler, VCS, telemetry, guardrails), integration tests (export, install, pipelines, VCS git+svn), and end-to-end tests (full agent lifecycle). Run npm test locally before opening a PR — CI runs the same suite on Node 22/24.

The @ci subagent enforces zero-tolerance for CI failures: invoked automatically before every merge, it inspects CI logs, fixes all failures (format, lint, test, validate, export, security), and iterates until every check passes. Invoke manually with @ci to debug a failing pipeline.

Documentation

| Document | Contents | |---|---|---| | ARCHITECTURE.md | Full internal architecture, core libraries, Guardrails, and API reference | | ORCHESTRATOR_MATRIX.md | Task → pipeline mapping and parallel execution groups | | AGENTS.md | Conventions and structure for writing agent definitions | | AGENTS_ANEX.md | Configuration annex — project-specific overrides and extensions | | SECURITY.md | Vulnerability reporting and security policy | | CHANGELOG.md | Release history | | CONTRIBUTING.md | How to add agents, models, and adapters |

Contributing

Contributions are welcome — especially new agent definitions, platform adapters, and model definitions. See CONTRIBUTING.md for the full workflow (adding an agent, adding a model, adding a platform adapter, commit conventions, and PR process). Issues and feature requests use the templates in .github/ISSUE_TEMPLATE/.

License

• packages/core, packages/sdk, packages/plugin-sdk, and everything under agents/, adapters/, schemas/, templates/, and tools/ are licensed under GPL-3.0-only — see LICENSE.
• packages/enterprise (SQLite storage, analytics, policy engine, and the Enterprise dashboard) is distributed under a separate commercial StaffForge license and is not covered by the GPL-3.0 grant above.

Support

• Bugs / feature requests: open an issue using the templates in .github/ISSUE_TEMPLATE/
• Questions about usage: see the Prompt examples and ORCHESTRATOR_MATRIX.md first
• Security issues: please do not open a public issue — contact the maintainer directly