@nntoan/gstack 0.0.1 → 0.3.0

package/README.md

@@ -1,33 +1,229 @@
-# gstack-opencode
+# @nntoan/gstack
 
-Use Garry Tan's exact OpenCode setup: 15 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA
+`@nntoan/gstack` is an OpenCode plugin + CLI that brings a structured multi-agent engineering workflow into your coding sessions.
 
-> A Bun module created from the [bun-module](https://github.com/zenobi-us/bun-module) template
+It ships with:
 
-## Usage
+- **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
 
-<!-- Example usage code goes here -->
+## Quick Start
 
-## Installation
+### 1) Install
 
-<!-- Installation instructions go here -->
+```bash
+npm i -g @nntoan/gstack
+```
+
+### 2) Register plugin and generate project config
+
+From your project root:
+
+```bash
+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
+
+```bash
+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:
+
+```bash
+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:
+
+```text
+.opencode/gstack.jsonc
+```
+
+Default template generated by `gstack install`:
+
+```jsonc
+{
+  "$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`](./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
 
-- `mise run build` - Build the module
-- `mise run test` - Run tests
-- `mise run lint` - Lint code
-- `mise run lint:fix` - Fix linting issues
-- `mise run format` - Format code with Prettier
+### 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
 
-See the [RELEASE.md](RELEASE.md) file for instructions on how to release a new version of the module.
+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
 
-Contributions are welcome! Please file issues or submit pull requests on the GitHub repository.
+Please follow [`CONTRIBUTING.md`](./CONTRIBUTING.md).
+
+Minimum bar before opening a PR:
+
+```bash
+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 the [LICENSE](LICENSE) file for details.
+See [LICENSE](./LICENSE).

package/dist/cli.js

@@ -5,25 +5,43 @@ var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toESMCache_node;
+var __toESMCache_esm;
 var __toESM = (mod, isNodeMode, target) => {
+  var canCache = mod != null && typeof mod === "object";
+  if (canCache) {
+    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
+    var cached = cache.get(mod);
+    if (cached)
+      return cached;
+  }
   target = mod != null ? __create(__getProtoOf(mod)) : {};
   const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
   for (let key of __getOwnPropNames(mod))
     if (!__hasOwnProp.call(to, key))
       __defProp(to, key, {
-        get: () => mod[key],
+        get: __accessProp.bind(mod, key),
         enumerable: true
       });
+  if (canCache)
+    cache.set(mod, to);
   return to;
 };
 var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
       get: all[name],
       enumerable: true,
       configurable: true,
-      set: (newValue) => all[name] = () => newValue
+      set: __exportSetter.bind(all, name)
     });
 };
 var __require = import.meta.require;
@@ -2139,7 +2157,7 @@ var {
 // package.json
 var package_default = {
   name: "@nntoan/gstack",
-  version: "0.0.1",
+  version: "0.3.0",
   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: {
     name: "Toan Nguyen",
@@ -2207,16 +2225,15 @@ var package_default = {
   optionalDependencies: {
     "@nntoan/gstack-darwin-arm64": "0.0.1",
     "@nntoan/gstack-darwin-x64": "0.0.1",
+    "@nntoan/gstack-darwin-x64-baseline": "0.0.1",
     "@nntoan/gstack-linux-arm64": "0.0.1",
     "@nntoan/gstack-linux-x64": "0.0.1",
+    "@nntoan/gstack-linux-x64-baseline": "0.0.1",
     "@nntoan/gstack-linux-arm64-musl": "0.0.1",
     "@nntoan/gstack-linux-x64-musl": "0.0.1",
-    "@nntoan/gstack-win32-arm64": "0.0.1",
+    "@nntoan/gstack-linux-x64-musl-baseline": "0.0.1",
     "@nntoan/gstack-win32-x64": "0.0.1",
-    "@nntoan/gstack-win32-ia32": "0.0.1",
-    "@nntoan/gstack-freebsd-x64": "0.0.1",
-    "@nntoan/gstack-freebsd-arm64": "0.0.1",
-    "@nntoan/gstack-openbsd-x64": "0.0.1"
+    "@nntoan/gstack-win32-x64-baseline": "0.0.1"
   },
   devDependencies: {
     "@eslint/js": "^9.39.1",
@@ -3043,7 +3060,7 @@ var ParseErrorCode;
 })(ParseErrorCode || (ParseErrorCode = {}));
 
 // src/config/schema/constants.ts
-var SCHEMA_URL = "https://raw.githubusercontent.com/nntoan/opencode-gstack/main/schemas/config.schema.json";
+var SCHEMA_URL = "https://raw.githubusercontent.com/nntoan/gstack-opencode/main/schemas/config.schema.json";
 
 // src/cli/install.ts
 var PROJECT_CONFIG_TEMPLATE = `{

package/dist/config/schema/constants.d.ts

@@ -1 +1 @@
-export declare const SCHEMA_URL = "https://raw.githubusercontent.com/nntoan/opencode-gstack/main/schemas/config.schema.json";
+export declare const SCHEMA_URL = "https://raw.githubusercontent.com/nntoan/gstack-opencode/main/schemas/config.schema.json";

package/dist/index.js

@@ -4,25 +4,43 @@ var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toESMCache_node;
+var __toESMCache_esm;
 var __toESM = (mod, isNodeMode, target) => {
+  var canCache = mod != null && typeof mod === "object";
+  if (canCache) {
+    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
+    var cached = cache.get(mod);
+    if (cached)
+      return cached;
+  }
   target = mod != null ? __create(__getProtoOf(mod)) : {};
   const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
   for (let key of __getOwnPropNames(mod))
     if (!__hasOwnProp.call(to, key))
       __defProp(to, key, {
-        get: () => mod[key],
+        get: __accessProp.bind(mod, key),
         enumerable: true
       });
+  if (canCache)
+    cache.set(mod, to);
   return to;
 };
 var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
       get: all[name],
       enumerable: true,
       configurable: true,
-      set: (newValue) => all[name] = () => newValue
+      set: __exportSetter.bind(all, name)
     });
 };
 var __require = import.meta.require;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nntoan/gstack",
-  "version": "0.0.1",
+  "version": "0.3.0",
   "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": {
     "name": "Toan Nguyen",
@@ -68,16 +68,15 @@
   "optionalDependencies": {
     "@nntoan/gstack-darwin-arm64": "0.0.1",
     "@nntoan/gstack-darwin-x64": "0.0.1",
+    "@nntoan/gstack-darwin-x64-baseline": "0.0.1",
     "@nntoan/gstack-linux-arm64": "0.0.1",
     "@nntoan/gstack-linux-x64": "0.0.1",
+    "@nntoan/gstack-linux-x64-baseline": "0.0.1",
     "@nntoan/gstack-linux-arm64-musl": "0.0.1",
     "@nntoan/gstack-linux-x64-musl": "0.0.1",
-    "@nntoan/gstack-win32-arm64": "0.0.1",
+    "@nntoan/gstack-linux-x64-musl-baseline": "0.0.1",
     "@nntoan/gstack-win32-x64": "0.0.1",
-    "@nntoan/gstack-win32-ia32": "0.0.1",
-    "@nntoan/gstack-freebsd-x64": "0.0.1",
-    "@nntoan/gstack-freebsd-arm64": "0.0.1",
-    "@nntoan/gstack-openbsd-x64": "0.0.1"
+    "@nntoan/gstack-win32-x64-baseline": "0.0.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.1",

package/schemas/config.schema.json

@@ -1,14 +1,11 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://raw.githubusercontent.com/nntoan/opencode-gstack/main/schemas/config.schema.json",
+  "$id": "https://raw.githubusercontent.com/nntoan/gstack-opencode/main/schemas/config.schema.json",
   "type": "object",
   "properties": {
     "orchestration_mode": {
       "type": "string",
-      "enum": [
-        "multi-agent",
-        "skills-only"
-      ],
+      "enum": ["multi-agent", "skills-only"],
       "default": "multi-agent",
       "description": "Orchestration mode for agent execution"
     },
@@ -73,10 +70,7 @@
           "properties": {
             "provider": {
               "type": "string",
-              "enum": [
-                "exa",
-                "tavily"
-              ],
+              "enum": ["exa", "tavily"],
               "default": "exa"
             },
             "api_key": {