npm package: @nntoan/gstack
Description: Use Garry Tan's exact OpenCode setup: 15 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA
Author: Toan Nguyen
Latest version: 0.7.0

# @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:

```bash
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):
>
> ```bash
> npm i -g @nntoan/gstack
> gstack install
> ```

### 2) Validate environment

```bash
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:

```bash
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:

```text
~/.config/opencode/gstack.jsonc
```

Default template generated by `bunx @nntoan/gstack install`:

```jsonc
{
  "$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`](./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`](./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`](./src/features/builtin-skills/skills/index.ts).

## Development

### Prerequisites

- [Bun](https://bun.sh/) runtime
- [mise](https://mise.jdx.dev/) (optional but recommended for task aliases)

### Install dependencies

```bash
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

```bash
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`](./AGENTS.md) — command standards, style rules, test/lint expectations
2. [`CLAUDE.md`](./CLAUDE.md) — GitNexus workflow and safety requirements
3. [`CONTRIBUTING.md`](./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:

```bash
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`](./src/cli/cli-program.ts)
- Install behavior: [`src/cli/install.ts`](./src/cli/install.ts)
- Plugin entry: [`src/index.ts`](./src/index.ts)
- Plugin interface hooks: [`src/plugin-interface.ts`](./src/plugin-interface.ts)
- Skills + agents composition: [`src/create-skills-and-agents.ts`](./src/create-skills-and-agents.ts)
- Orchestrator: [`src/features/orchestrator/`](./src/features/orchestrator)
- MCP integrations: [`src/mcp/`](./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`](./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`](./CONTRIBUTING.md).

Minimum bar before opening a PR:

```bash
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`](./AGENTS.md) — engineering and code quality rules
- [`CONTRIBUTING.md`](./CONTRIBUTING.md) — PR and contribution process
- [`RELEASE.md`](./RELEASE.md) — release and publishing workflows

## License

See [LICENSE](./LICENSE).