@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

npm i -g @nntoan/gstack

2) Register plugin and generate project config

From your project root:

gstack install

This command does two things:

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

3) Validate environment

gstack doctor

You're ready when doctor reports no blocking configuration/environment issues and your project contains .opencode/gstack.jsonc.

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. Project directory is writable (for .opencode/gstack.jsonc)

Then run:

gstack doctor

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

What Gets Installed

CLI commands

• gstack install — bootstrap local config + plugin registration
• gstack doctor — run environment/config health checks

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 project-level config lives at:

.opencode/gstack.jsonc

Default template generated by gstack install:

{
  "$schema": "https://raw.githubusercontent.com/nntoan/gstack-opencode/main/schemas/config.schema.json",
  "orchestration_mode": "multi-agent",
  "disabled_agents": [],
  "disabled_skills": [],
}

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:

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.