superspec-ai-workflow — AI-Driven Development Blueprint

AI-Assisted Monorepo Development Workflow
Blueprint for building multi-platform applications using OpenCode + OMO + OpenSpec + Superpowers

Projects • Tech Stack • Features • Quick Start • Architecture • AI Workflow

Overview

This repository demonstrates an AI-assisted development workflow for building multi-platform applications as a monorepo containing:

Mobile App — Cross-platform React Native app for end-users
Web Dashboard — Next.js admin panel
REST API — Go backend with Clean Architecture
API Collection — Bruno API testing collection (YAML-based, git-friendly)

The workflow itself — powered by OpenCode, OMO agent orchestration, OpenSpec change management, and Superpowers skills — is the main artifact. Fork this repo to bootstrap your own AI-driven development pipeline.

Projects

Project	Technology	Description
`{project-name}-mobile`	React Native + TypeScript	Mobile app for iOS/Android with role-based access
`{project-name}-frontend`	Next.js + Tailwind CSS	Web admin dashboard
`{project-name}-backend`	Go + Gin + GORM	REST API with Clean Architecture
`{project-name}-bruno`	Bruno (YAML)	API testing collection
`{project-name}-regional`	Go	Regional data service

Tech Stack

Backend

Component	Technology
Language	Go
Framework	Gin
ORM	GORM
Database	PostgreSQL
Cache	Redis
Search	Typesense
Auth	JWT (golang-jwt)
Push	Firebase FCM
Storage	AWS S3 / DigitalOcean Spaces / SeaweedFS

Mobile

Component	Technology
Framework	React Native CLI
Language	TypeScript
UI	React Native Paper
State	Jotai (client) + TanStack Query (server)
Navigation	React Navigation
Forms	React Hook Form + Zod
Storage	MMKV
Maps	React Native Maps
Camera	Vision Camera

Frontend

Component	Technology
Framework	Next.js
Language	TypeScript
Styling	Tailwind CSS
Components	shadcn/ui (Radix UI)
State	Redux Toolkit + RTK Query
Forms	React Hook Form + Zod
Charts	Chart.js
Testing	Jest + Playwright

Features

AI-Assisted Development Workflow

Capability	Tooling	Benefit
Intent-Based Planning	Prometheus agent + OpenSpec propose	Specs written before code
Parallel Research	Explore + Librarian agents	3-5 parallel codebase searches
Skill-Guided Execution	Superpowers (TDD, debugging, etc.)	Repeatable quality
Evidence-Based Verification	Build + test + manual QA	No claims without proof
Change Audit Trail	OpenSpec archive	Every change documented
Token Optimization	RTK + OMNI + Caveman stack	60-90% context savings

AI Workflow Roles

Role	Agent	Responsibility
Orchestrator	Sisyphus	Decompose, delegate, verify — never executes directly
Strategic Planner	Prometheus	Interview, explore, produce detailed plans
Master Executor	Atlas	Execute verified plans with checkpoints
Research	Explore / Librarian	Codebase grep, external reference search
Reviewer	Momus / Metis / Oracle	Plan validation, code review, gap analysis
Deep Worker	Hephaestus	End-to-end for architectural work

Quick Start

Prerequisites

Node.js >= 18
Go >= 1.25
PostgreSQL >= 14
Redis >= 7
Docker (optional, for local services)
OpenCode (or Claude Code) — AI coding agent
OpenSpec CLI — change management

1. Clone & Fork

git clone <repository-url>
cd {project-name}

2. Install AI Workflow Tooling

# OpenCode
npm install -g @opencode/cli

# OpenSpec
npm install -g openspec

# Verify
opencode --version
openspec --version

3. Initialize Project-Specific Skills

# Bootstrap AI workflow configuration
# Modify .agents/skills/ and .agents/rules/ for your project

# See AGENTS.md for full setup guide

4. Setup Backend

cd {project-name}-backend

# Copy environment
cp env.example .env

# Install dependencies
go mod download

# Run with Docker Compose (PostgreSQL + Redis + Typesense)
docker-compose -f docker-compose.local.yml up -d

# Run migrations
./scripts/migrate-local.sh

# Run seeders
./scripts/seeder-local.sh

# Start server
./scripts/run-local.sh

5. Setup Mobile

cd {project-name}-mobile

# Install dependencies
yarn install

# iOS setup (macOS only)
cd ios && bundle exec pod install && cd ..

# Create environment
cp .env.example .env

# Start Metro
yarn start

# Run on Android
yarn android

# Run on iOS
yarn ios

6. Setup Frontend

cd {project-name}-frontend

# Install dependencies
npm install

# Create environment
cp .env.development .env.local

# Run development server
npm run dev

7. API Testing (Bruno)

# Install Bruno
brew install --cask bruno  # macOS

# Open collection
bruno open {project-name}-bruno

Architecture

Backend (Clean Architecture)

┌─────────────────────────────────────────────────────────────┐
│                      cmd/                                   │
│  ├── server/     # Main API server                          │
│  ├── migrator/   # Database migrations                      │
│  └── seeder/     # Database seeders                         │
└─────────────────────────────────────────────────────────────┘
                            │
┌─────────────────────────────────────────────────────────────┐
│                    internal/                                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  handler/   │  │  service/   │  │ repository/ │         │
│  │  (HTTP)     │──│  (Business) │──│  (Data)     │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
│         │                │                │                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │   dto/      │  │   domain/   │  │ middleware/ │         │
│  │ (Requests)  │  │  (Models)   │  │  (Auth/RBAC)│         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘

Mobile (Feature-Based)

src/
├── core/                    # Infrastructure & shared code
│   ├── libs/               # Third-party setups
│   ├── services/           # API services
│   ├── states/             # Jotai + TanStack Query
│   └── styles/             # Design tokens
│
└── features/               # Domain modules
    ├── auth/              # Authentication
    ├── main-module/       # Primary domain
    ├── billing/           # Finance
    └── ...                # Feature modules

Frontend (App Router)

app/
├── (auth)/                # Auth routes (no sidebar)
├── dashboard/            # Role-based dashboard
├── module-one/           # Module group
├── module-two/           # Module group
└── ...                   # Feature modules

API Documentation

Swagger UI

Interactive API docs available at:

http://localhost:8080/swagger/index.html

API Versions

Version	Base Path	Purpose
v1	`/api/v1/*`	Web dashboard endpoints
Mobile v1	`/api/mobile/v1/*`	Mobile-optimized endpoints

Documentation

Project Documentation

Document	Location	Description
Backend README	`{project-name}-backend/README.md`	Backend development guide
Mobile README	`{project-name}-mobile/README.md`	Mobile development guide
Frontend README	`{project-name}-frontend/README.md`	Web dashboard guide
Bruno README	`{project-name}-bruno/README.md`	API testing guide

AI Development Guidelines

AGENTS.md — Main AI agent guidelines
.agents/rules/ — Coding rules and constraints
.agents/skills/ — Specialized development skills

AI Workflow Architecture

This project uses an AI-driven development workflow powered by OpenCode + OMO + OpenSpec + Superpowers:

┌─────────────────────────────────────────────────────────────┐
│                    AI WORKFLOW STACK                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │   User      │───→│  Sisyphus   │───→│   Plan      │     │
│  │  Request    │    │  (Orchestrator)   │  Agent      │     │
│  └─────────────┘    └─────────────┘    └──────┬──────┘     │
│                              │                  │            │
│                              ▼                  ▼            │
│                    ┌───────────────────────────────────┐     │
│                    │    Intent Classification          │     │
│                    │    Skill Loading (mandatory)      │     │
│                    └───────────────────────────────────┘     │
│                              │                               │
│              ┌───────────────┼───────────────┐               │
│              ▼               ▼               ▼               │
│      ┌──────────┐   ┌──────────┐   ┌──────────┐            │
│      │ Research │   │  Plan    │   │ Execute  │            │
│      │ (explore)│   │ (Prometheus)│  │(Sisyphus-│            │
│      │(librarian)│  │          │   │  Junior) │            │
│      └──────────┘   └────┬─────┘   └────┬─────┘            │
│                          │              │                   │
│                          ▼              ▼                   │
│              ┌──────────────────────────────────────┐       │
│              │    Parallel Task Delegation          │       │
│              │    category + skills per task        │       │
│              └──────────────────────────────────────┘       │
│                              │                               │
│                              ▼                               │
│              ┌──────────────────────────────────────┐       │
│              │    Evidence-Based Verification       │       │
│              │    Build → Test → Manual QA          │       │
│              └──────────────────────────────────────┘       │
│                              │                               │
│                              ▼                               │
│              ┌──────────────────────────────────────┐       │
│              │    OpenSpec Archive                  │       │
│              │    Change finalized & documented     │       │
│              └──────────────────────────────────────┘       │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Workflow Steps

Step	Tool	Purpose
1. Propose	`/opsx:propose` (OpenSpec)	Structured change proposal with specs, design, task decomposition
2. Explore	`task(subagent_type="explore")`	Parallel codebase research (3-5 agents)
3. Plan	`task(subagent_type="plan")` (Prometheus)	Task decomposition with dependency graph
4. Apply	`/opsx:apply` (OpenSpec)	Delegated execution via category + skills
5. Verify	`verification-before-completion` skill	Build + test + manual QA evidence
6. Archive	`/opsx:archive` (OpenSpec)	Change finalized with audit trail

Example Outputs

OpenSpec Example — Full change proposal with specs, design, tasks, and execution log
Superpowers Example — Complete workflow output from proposal to archive

Token Optimization Stack

Three-layer optimization keeps context efficient:

Layer	Tool	Savings
RTK	`rtk <cmd>`	60-90% on CLI I/O
OMNI	Output filtering	Strips noise, keeps signal
Caveman	Compressed prose	~75% on AI communication

Development Commands

Backend

cd {project-name}-backend

# Run server
./scripts/run-local.sh

# Run migrations
./scripts/migrate-local.sh

# Run seeders
./scripts/seeder-local.sh

# Build binary
go build -o server ./cmd/server

Mobile

cd {project-name}-mobile

# Start Metro
yarn start

# Run Android
yarn android

# Run iOS
yarn ios

# Build APK
yarn build:apk

# Lint
yarn lint

Frontend

cd {project-name}-frontend

# Dev server
npm run dev

# Build
npm run build

# Lint
npm run lint

# Test
npm test

Project Structure

{project-name}/
├── {project-name}-backend/       # Go REST API
│   ├── cmd/                 # Entry points
│   ├── internal/            # Application code
│   ├── migrations/          # SQL migrations
│   ├── scripts/             # Dev scripts
│   └── docs/                # API docs
│
├── {project-name}-mobile/       # React Native app
│   ├── src/
│   │   ├── core/           # Infrastructure
│   │   └── features/       # Domain modules
│   ├── ios/                # iOS native
│   └── android/            # Android native
│
├── {project-name}-frontend/     # Next.js web dashboard
│   ├── app/                # App Router
│   ├── components/         # React components
│   ├── lib/                # Utilities
│   └── data/               # Configurations
│
├── {project-name}-bruno/        # Bruno API collection
│   ├── environments/       # API environments
│   ├── auth/               # Auth endpoints
│   └── Mobile App/         # Mobile endpoints
│
├── {project-name}-regional/  # Regional data service
│
├── .agents/                 # AI development rules & skills
│   ├── rules/              # Coding constraints
│   └── skills/             # Task templates
│
├── notes/                   # Project documentation
│   ├── docs/               # Reference docs
│   └── archives/           # Legacy docs
│
└── README.md               # This file

Docker Services

Local Development

cd {project-name}-backend

# Start all services
docker-compose -f docker-compose.local.yml up -d

# Services started:
# - PostgreSQL (port 5432)
# - Redis (port 6379)
# - Typesense (port 8108)
# - SeaweedFS (port 8333)

Production

# Backend
docker-compose up -d

# Frontend
cd {project-name}-frontend
docker-compose -f docker-compose-prd.yml up -d

Adapting This Blueprint

This repository is a workflow blueprint, not a fixed product. To adapt it for your own project:

Replace {project-name} throughout with your project's identifier
Update .agents/rules/ — coding constraints for your tech stack
Update .agents/skills/ — skill definitions for your domain
Modify AGENTS.md — agent directives for your architecture
Swap example docs in docs/ with your own OpenSpec changes
Keep the AI workflow infrastructure — it's the main value

The AI workflow (OMO + OpenSpec + Superpowers) is framework-agnostic. It works for any language, any stack, any team size.

License

MIT — See LICENSE for details.

superspec-ai-workflow — AI-Driven Development Blueprint
Built with OpenCode • OMO • OpenSpec • Superpowers

Name		Name	Last commit message	Last commit date
.agents		.agents
docs		docs
openspec		openspec
AGENTS.md		AGENTS.md
README.md		README.md
opencode.json		opencode.json
skills-lock.json		skills-lock.json

Latest commit

History

Folders and files

Repository files navigation

superspec-ai-workflow — AI-Driven Development Blueprint

Overview

Projects

Tech Stack

Backend

Mobile

Frontend

Features

AI-Assisted Development Workflow

AI Workflow Roles

Quick Start

Prerequisites

1. Clone & Fork

2. Install AI Workflow Tooling

3. Initialize Project-Specific Skills

4. Setup Backend

5. Setup Mobile

6. Setup Frontend

7. API Testing (Bruno)

Architecture

Backend (Clean Architecture)

Mobile (Feature-Based)

Frontend (App Router)

API Documentation

Swagger UI

API Versions

Documentation

Project Documentation

AI Development Guidelines

AI Workflow Architecture

Workflow Steps

Example Outputs

Token Optimization Stack

Development Commands

Backend

Mobile

Frontend

Project Structure

Docker Services

Local Development

Production

Adapting This Blueprint

License

About

Topics

Resources

Stars

Watchers

Forks

Contributors