@nntoan/gstack

@nntoan/gstack is an OpenCode plugin + CLI that brings a structured multi-agent engineering workflow into your coding sessions.

It ships with:

• 13 built-in agents (CEO, Eng Manager, Designer, Builder, Reviewer, Debugger, QA Lead, Release Engineer, Doc Engineer, Retro Lead, Safety Guard, Upgrader, Session Manager)
• 25 built-in skills for planning, implementation, QA, release, investigation, and safety checks
• Bun-first DX with reproducible build/test/lint/typecheck scripts

Quick Start

1) Install and register

A single command installs the plugin, generates your global config, and registers it with OpenCode:

bunx @nntoan/gstack install

This does two things:

1. Creates global config at ~/.config/opencode/gstack.jsonc (if missing)
2. Adds @nntoan/gstack to your global OpenCode plugin list at ~/.config/opencode/opencode.json

Alternative (if you prefer a global install):

npm i -g @nntoan/gstack
gstack install

2) Validate environment

bunx @nntoan/gstack doctor

You're ready when doctor reports no blocking issues and ~/.config/opencode/gstack.jsonc exists.

First-Run Troubleshooting

If onboarding fails, check these first:

1. HOME is available (required for ~/.config/opencode/opencode.json updates)
2. OpenCode global config is writable (~/.config/opencode/opencode.json)
3. OpenCode config directory is writable (for ~/.config/opencode/gstack.jsonc)

Then run:

bunx @nntoan/gstack doctor

If you still have issues, include doctor output and your Bun/OS environment when opening an issue.

Note: OpenCode agent config uses the agent key (singular). gstack writes to this shape via its config handler.

What Gets Installed

CLI commands

| Command | Via bunx (no install) | Via global install | | ------- | ----------------------------- | ------------------ | | Install | bunx @nntoan/gstack install | gstack install | | Doctor | bunx @nntoan/gstack doctor | gstack doctor |

Plugin runtime flow

At runtime, the plugin entry (src/index.ts) does:

1. Load plugin config
2. Create skills + agents
3. Create managers
4. Create orchestrator
5. Register tools + hooks
6. Return plugin interface handlers (chat.message, event, tool hooks)

Configuration

Your global config lives at:

~/.config/opencode/gstack.jsonc

Default template generated by bunx @nntoan/gstack install:

{
  "$schema": "https://raw.githubusercontent.com/nntoan/gstack-opencode/main/schemas/config.schema.json",
  "agents": {
    "ceo": { "model": "opencode/gpt-5-nano" },
    "eng-manager": { "model": "opencode/gpt-5-nano" },
    "designer": { "model": "opencode/gpt-5-nano" },
    "builder": { "model": "opencode/gpt-5-nano" },
    "reviewer": { "model": "opencode/gpt-5-nano" },
    "debugger": { "model": "opencode/gpt-5-nano" },
    "qa-lead": { "model": "opencode/gpt-5-nano" },
    "release-engineer": { "model": "opencode/gpt-5-nano" },
    "doc-engineer": { "model": "opencode/gpt-5-nano" },
    "retro-lead": { "model": "opencode/gpt-5-nano" },
    "safety-guard": { "model": "opencode/gpt-5-nano" },
    "upgrader": { "model": "opencode/gpt-5-nano" },
    "session-manager": { "model": "opencode/gpt-5-nano" },
  },
}

The installer intentionally writes a minimal config ($schema + agents). Other settings like orchestration_mode and disabled_* are optional and use schema defaults.

Schema file in this repo: schemas/config.schema.json

Important top-level config keys:

• orchestration_mode: multi-agent | skills-only
• disabled_agents: string[]
• disabled_skills: string[]
• disabled_mcps: string[]
• disabled_hooks: string[]
• agents: per-agent overrides (model, instructions, enabled)
• mcp: provider and enable/disable controls (websearch, context7, contexthub, grep_app, backlog_md)
• backlog, browser, telemetry

Agent System Overview

All built-in agents are registered in src/agents/index.ts.

| Agent role | Purpose | | ------------------ | ----------------------------------------- | | ceo | Strategic direction and decomposition | | eng-manager | Planning and execution framing | | designer | UX and product-design decisions | | builder | Implementation execution | | reviewer | Code quality and review | | debugger | Root-cause analysis and fixes | | qa-lead | Test strategy and quality assurance | | release-engineer | Release readiness and publishing flow | | doc-engineer | Documentation and handoff quality | | retro-lead | Retrospectives and process improvement | | safety-guard | Risk/safety policy checks | | upgrader | Dependency/runtime upgrade guidance | | session-manager | Session continuity and context management |

Built-in skills are exported from src/features/builtin-skills/skills/index.ts.

Development

Prerequisites

• Bun runtime
• mise (optional but recommended for task aliases)

Install dependencies

bun install

Core commands

• Build library: bun run build
• Build CLI: bun run build:cli
• Build all: bun run build:all
• Test: bun run test
• Typecheck: bun run typecheck
• Lint: bun run lint
• Lint fix: bun run lint:fix
• Format: bun run format

Equivalent mise shortcuts:

• mise run build
• mise run test
• mise run lint
• mise run lint:fix
• mise run format

Typical local CI loop

bun run test && bun run typecheck && bun run lint && bun run build:all

For Autonomous Coding Agents

If you are an AI coding agent contributing to this repo, read these first:

1. AGENTS.md — command standards, style rules, test/lint expectations
2. CLAUDE.md — GitNexus workflow and safety requirements
3. CONTRIBUTING.md — PR and commit conventions

Required workflow guardrails:

• Run impact analysis before symbol edits (gitnexus_impact)
• Run change-scope checks before commit (gitnexus_detect_changes)
• Use Conventional Commits
• Keep no-console and strict TypeScript requirements intact

Safe local validation loop before proposing changes:

bun run test && bun run typecheck && bun run lint && bun run build:all

Architecture Map (Where to Start)

• CLI definition: src/cli/cli-program.ts
• Install behavior: src/cli/install.ts
• Plugin entry: src/index.ts
• Plugin interface hooks: src/plugin-interface.ts
• Skills + agents composition: src/create-skills-and-agents.ts
• Orchestrator: src/features/orchestrator/
• MCP integrations: src/mcp/

If you are new to the codebase, start with src/cli/install.ts and src/index.ts.

Release

Release automation is documented in RELEASE.md.

Short version:

• Standard releases go through Release Please (.github/workflows/release-please.yml)
• Manual fallback publishing exists in .github/workflows/publish.yml

Contributing

Please follow CONTRIBUTING.md.

Minimum bar before opening a PR:

bun run test
bun run lint

Or with mise: mise run test / mise run lint

Use Conventional Commits for commit messages and PR titles.

Documentation Map

• AGENTS.md — engineering and code quality rules
• CONTRIBUTING.md — PR and contribution process
• RELEASE.md — release and publishing workflows

License

See LICENSE.