Engineering AI Programming: A Complete Closed Loop with OpenSpec‑Driven Specs and gstack Role Execution

gstack Overview

gstack is an open‑source Claude Code skill set (23+ role‑based skills) that turns a single AI assistant into a virtual engineering team. Core idea: assign distinct roles (CEO, Engineering Manager, Engineer, QA, Release Manager, Designer, Documentation Engineer, DevEx) to simulate a full team.

CEO – /gstack:ceo – product strategy, vision, high‑level requirements

Engineering Manager – /gstack:eng-manager – architecture review, code quality, technical planning

Engineer – /gstack:engineer – feature implementation, production‑grade code

QA – /gstack:qa – browser testing, test‑suite authoring

Release Manager – /gstack:release-manager – versioning, changelog, deployment preparation

Designer – /gstack:design – UI/UX design review

Documentation Engineer – /gstack:doc – technical documentation

DevEx – /gstack:devex – developer experience improvements

Why combine OpenSpec + gstack

OpenSpec provides a structured specification layer and change‑traceability; gstack provides a role‑based execution layer. Together they create a “spec‑driven + role‑division” double‑engine that fills quality‑gate and release‑process gaps.

Unclear requirements → structured spec docs (OpenSpec) + strategic input from CEO role (gstack) → guaranteed alignment.

Role confusion → 23 explicit roles (gstack) + spec‑driven role collaboration (OpenSpec).

Quality assurance → behavior verification (OpenSpec) + QA + Engineering Manager review (gstack) → multi‑layer quality gates.

Change traceability → full archiving mechanism (OpenSpec) + Git history (gstack) → complete traceability.

Deployment & release → dedicated Release Manager role (gstack) + spec acceptance flow (OpenSpec).

Installation & Configuration

System requirements

Node.js ≥ 20.19.0 ( node --version)

Claude Code (latest version, claude --version)

Git ≥ 2.30 ( git --version)

Install OpenSpec

# Global install OpenSpec
npm install -g @fission-ai/openspec@latest

# Verify installation
openspec --version
openspec --help

Install gstack (one‑click)

# Clone gstack into Claude Code skills directory and run setup
git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup

Verify installation

/gstack:help

Full workflow example – User authentication system

Phase 1 – Strategy & Specification

Step 1 – CEO strategic input

/gstack:ceo
"I want to build a user system for an e‑commerce platform supporting email registration, Google/GitHub OAuth, JWT authentication, and user profile management. Target: quick MVP for SMBs."

CEO output includes vision, MVP features, V2 roadmap, and success metrics (registration conversion > 60 %, API latency < 200 ms, zero security bugs).

Step 2 – OpenSpec exploration

/opsx:explore "Based on the strategic doc, explore technical implementation for the user‑auth system."

Exploration report recommends Node.js + Express, PostgreSQL + Redis, JWT + bcrypt, Passport.js and lists risks (SQL injection, XSS, performance, GDPR).

Step 3 – OpenSpec proposal

/opsx:propose "User authentication system MVP"

Generated artifact tree:

openspec/changes/user-auth-mvp/
├── proposal.md
├── design.md
├── specs/
│   └── user-auth/
│       └── spec.md
└── tasks.md

Step 4 – Engineering Manager review

/gstack:eng-manager
"Please review the design doc focusing on architecture soundness, tech choices, and risk assessment."

Review output contains ✅ passed items, ⚠️ suggestions (rate‑limiting, Argon2), ❌ risks (missing DB migration, no monitoring) and a checklist.

Step 5 – Update specs

# Edit openspec/changes/user-auth-mvp/design.md to add rate‑limiting, password rules, migration plan

Phase 2 – Role‑based execution

Step 6 – Task breakdown

/gstack:eng-manager
"Based on tasks.md, break down each task to fit within 2‑4 hours."

Resulting refined task list (example):

## Phase 1: Infrastructure (Day 1‑2)
- [ ] Init Node.js project (express, typescript, eslint)
- [ ] Configure PostgreSQL connection
- [ ] Create User model (id, email, password_hash, created_at)
- [ ] Implement password‑hash utility (bcrypt)

## Phase 2: Auth features (Day 3‑4)
- [ ] POST /api/auth/register
- [ ] POST /api/auth/login
- [ ] JWT utilities (access & refresh tokens)
- [ ] Auth middleware (verifyToken)

## Phase 3: User profile (Day 5‑6)
- [ ] GET /api/users/:id
- [ ] PUT /api/users/:id
- [ ] Optional avatar upload

## Phase 4: Test & docs (Day 7)
- [ ] Unit tests (Jest)
- [ ] API docs (Swagger)
- [ ] Deploy test environment

Step 7 – Engineer implementation

/gstack:engineer
"Implement tasks 1.1‑1.4 following these guidelines: TypeScript, ESLint, JSDoc, full error handling."

Sample User model implementation:

import { Pool, QueryResult } from 'pg';
import bcrypt from 'bcrypt';

const SALT_ROUNDS = 12;

export interface User {
  id: string;
  email: string;
  password_hash: string;
  created_at: Date;
}

export class UserModel {
  constructor(private pool: Pool) {}

  /** Create a new user */
  async create(email: string, password: string): Promise<User> {
    const password_hash = await bcrypt.hash(password, SALT_ROUNDS);
    const result: QueryResult<User> = await this.pool.query(
      'INSERT INTO users (email, password_hash) VALUES ($1, $2) RETURNING *',
      [email, password_hash]
    );
    return result.rows[0];
  }

  /** Find user by email */
  async findByEmail(email: string): Promise<User | null> {
    const result: QueryResult<User> = await this.pool.query(
      'SELECT * FROM users WHERE email = $1',
      [email]
    );
    return result.rows[0] || null;
  }
}

Step 8 – QA testing

/gstack:qa
"Write a test suite for the User model and auth endpoints with ≥80 % coverage, including boundary and security tests (SQL injection, XSS)."

Sample registration test:

describe('POST /api/auth/register', () => {
  it('registers with valid email and password', async () => {
    const response = await request(app)
      .post('/api/auth/register')
      .send({ email: '[email protected]', password: 'SecurePass123!' });
    expect(response.status).toBe(201);
    expect(response.body.user.email).toBe('[email protected]');
    expect(response.body.user.password).toBeUndefined();
  });

  it('rejects invalid email format', async () => {
    const response = await request(app)
      .post('/api/auth/register')
      .send({ email: 'invalid-email', password: 'SecurePass123!' });
    expect(response.status).toBe(400);
    expect(response.body.error).toContain('email');
  });

  it('rejects weak password', async () => {
    const response = await request(app)
      .post('/api/auth/register')
      .send({ email: '[email protected]', password: '123' });
    expect(response.status).toBe(400);
    expect(response.body.error).toContain('password');
  });

  it('prevents SQL injection', async () => {
    const response = await request(app)
      .post('/api/auth/register')
      .send({ email: "test' OR '1'='1", password: 'SecurePass123!' });
    expect(response.status).toBe(400);
  });
});

Phase 3 – Verification & Release

Step 10 – OpenSpec verification

/opsx:verify

Verification report shows 100 % spec coverage, 87 % test coverage (≥80 % target), ESLint pass, and security tests passed.

Step 11 – Release Manager preparation

/gstack:release-manager
"Prepare release: generate changelog, check deployment checklist, draft release notes."

Release notes list features, security measures, deployment checklist, known limitations, and V2 roadmap.

Step 12 – Archive change

/opsx:archive

Archive structure:

openspec/changes/archive/2026-04-21-user-auth-mvp/
├── proposal.md
├── design.md
├── specs/user-auth/spec.md
├── tasks.md
└── release-notes.md

Best‑practice highlights

Invoke roles in the order: CEO → Engineering Manager → Engineer → QA → Designer → Release Manager.

Never let an Engineer code before a spec exists; define the spec, then assign the task.

Change‑management strategies:

Small change (<4 h): /opsx:ff → /gstack:engineer → /gstack:qa → /opsx:archive Medium change (1‑3 days): full proposal, reviews, implementation, testing, verification, archiving, release.

Large change (>3 days): split into sub‑changes and run the standard flow for each.

Effectiveness metrics

Spec coverage ≥ 95 % (spec items vs implemented features)

Role participation ≥ 3 distinct roles per change

Test coverage ≥ 80 %

Rework rate < 15 %

Release success rate ≥ 90 %

Practical case study – Blog comment system

The workflow mirrors the user‑auth example. Result: 100 % spec coverage, 85 % test coverage, involvement of five roles, and a 5 % rework rate.

Conclusion

OpenSpec excels at spec management and traceability; gstack excels at role division and execution. Their combination yields clear strategy, robust spec management, explicit role responsibilities, strong quality assurance, and full change traceability.

Action checklist

# 1. Install OpenSpec
npm install -g @fission-ai/openspec@latest

# 2. Install gstack
git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup

# 3. Initialise a project
mkdir test-combo && cd test-combo
openspec init

# 4. Run a first change
/gstack:ceo "Create a Hello World project"
/opsx:ff "Hello World feature"

Resources

OpenSpec GitHub: https://github.com/Fission-AI/OpenSpec

gstack GitHub: https://github.com/garrytan/gstack

OpenSpec documentation: https://openspec.dev/

gstack documentation: https://github.com/garrytan/gstack/blob/main/docs/

Discord community: https://discord.gg/YctCnvvshC