agent-stack

Scaffolds a universal multi-agent OpenCode workflow into any project. Two commands set everything up — then open OpenCode and start building.

Prerequisites

• Bun — used to run the CLI
• OpenCode — the AI coding tool that runs the agents

Setup

Step 1 — Bootstrap

Navigate to your project root and run:

cd my-project
bunx agent-stack init

This copies the universal agent and skill files into .opencode/ and writes a stub config:

my-project/
└── .opencode/
    ├── opencode.json      ← model config stub
    ├── profile.json       ← project profile stub (filled in step 2)
    ├── agents/            ← 14 universal agents
    ├── commands/
    │   └── setup.md       ← /setup slash command
    └── skills/            ← 15 core skills

Step 2 — Configure

Still in the terminal (before opening OpenCode), run:

bunx agent-stack setup

This launches an interactive terminal wizard that:

1. Auto-detects your project name, branch, stack, and commands from the filesystem
2. Prompts you to confirm or override each field
3. Writes .opencode/profile.json with your project config
4. Updates .opencode/opencode.json with your chosen model assignments

Step 3 — Open OpenCode and run /setup

opencode

Then run /setup once. The setup agent reads your already-written profile.json and:

1. Resolves the right skills per agent role
2. Generates tech-specific developer agents (e.g. backend-developer.md) from your stack

Agents

Coordinator agents (primary — call from OpenCode)

Agent	How to invoke	Purpose
implementer	/implementer	Full feature implementation workflow
debugger	/debugger	Bug diagnosis and fix workflow
issue-manager	/issue-manager	Create and manage GitHub issues

Core subagents (called automatically by coordinators)

researcher → ui-designer → designer → planner → plan-reviewer → tester → reviewer → cleaner → formatter → commiter

Developer agents (generated by /setup)

One agent per active layer, written from scratch by the setup agent for your specific stack. Examples:

Layer	Agent	Generated for
Backend	backend-developer	e.g. Go + PostgreSQL, Python/FastAPI, Node.js
Frontend	frontend-developer	e.g. Next.js, Vue/Nuxt, React
Mobile	mobile-developer	e.g. Kotlin/Android, Swift/iOS, React Native
Infrastructure	infra-developer	e.g. AWS + Terraform, GCP, Kubernetes

Skills

Skills are markdown documents that agents load at runtime via skill("name") to gain domain knowledge without bloating their base prompts.

Core skills (always installed)

Skill	Purpose
git-workflow	Branch naming, commit conventions, PR workflow
code-review	Code review checklists and standards
self-healing	Error recovery and retry patterns
three-layer-testing	Unit / integration / E2E testing strategy
output-discipline	Consistent, concise agent output formatting
find-skills	How to discover and load skills at runtime
mermaid-diagrams	Mermaid syntax reference for all diagram types
architecture-patterns	Common software architecture patterns
implement-design	Translating design docs into implementation plans
ui-ux-pro-max	UX/UI best practices and design patterns
web-design-guidelines	Web design principles and conventions
research	Structured research and caching patterns
github-issues	GitHub issue templates, labels, and gh CLI workflows
github-workflow	Full gh CLI reference for issues, PRs, and Actions

Tech-specific skills

The /setup agent resolves tech-specific skills for each agent role and writes them into profile.skills in opencode.json. Agents load only the skills relevant to their role. Additional skills can be added from skills.sh or written manually into .opencode/skills/.

Profile schema

After /setup, your opencode.json profile section looks like:

{
  "profile": {
    "project_name": "my-app",
    "default_branch": "main",
    "has_backend": true,
    "has_frontend": true,
    "has_mobile": false,
    "has_infra": false,
    "has_database": true,
    "platform": "web",
    "arch_pattern": "layered-mvc",
    "commands": {
      "build": "make build",
      "test": "make test",
      "lint": "make lint",
      "format": "make format",
      "typecheck": "npx tsc --noEmit",
      "e2e": "npx playwright test"
    },
    "paths": {
      "backend_src": "backend/internal",
      "frontend_src": "web/src"
    },
    "agents": {
      "backend-developer": { "promptFile": "agents/backend-developer.md", "tech": "Go + PostgreSQL" },
      "frontend-developer": { "promptFile": "agents/frontend-developer.md", "tech": "Next.js + React Query" }
    },
    "skills": {
      "implementer": ["git-workflow", "code-review", "self-healing"],
      "backend-developer": ["git-workflow", "go-backend-patterns", "three-layer-testing"],
      "frontend-developer": ["git-workflow", "nextjs-app-router", "three-layer-testing"]
    }
  }
}

All agents read profile.commands for the right commands to run, profile.paths for where source files live, and profile.skills.<role> for which skills to load. No tech knowledge is hardcoded in any agent file.

Development

Clone and run locally:

git clone https://github.com/maki5/agent-stack
cd agent-stack
bun install
bun run start         # run the CLI
bun run dev           # run with file watching

To test against a sample project:

mkdir /tmp/test-project
bun run start init --dir /tmp/test-project