Your system for spec-driven agentic development

Agent OS transforms AI coding agents from confused interns into productive developers. With structured workflows that capture your standards, your stack, and the unique details of your codebase, Agent OS gives your agents the specs they need to ship quality code on the first try—not the fifth.

Built for OpenCode with the opencode-skills plugin.

✅ New products or established codebases ✅ Big features, small fixes, or anything in between ✅ Any language or framework

---

Prerequisites

1. OpenCode

Install OpenCode if you haven't already:

• Documentation: https://opencode.ai/docs

2. OpenCode-Skills Plugin (Required)

Agent-OS uses OpenCode Skills, which requires the opencode-skills plugin.

Installation Steps:

1. Clone and install the plugin:

   git clone https://github.com/malhashemi/opencode-skills
   cd opencode-skills
   npm install

2. Add to your OpenCode config (~/.config/opencode/opencode.json):

   {
     "plugin": ["opencode-skills"]
   }

3. Restart OpenCode - the plugin will auto-load on startup

---

Installation

Step 1: Clone Agent-OS

git clone https://github.com/netixc/agent-os

Step 2: Review Configuration (Optional)

Check config.yml and modify if needed:

cd agent-os
cat config.yml

Key settings:

• opencode_commands: true - Install commands to .opencode/command/
• use_opencode_agents: true - Install agents to .opencode/agent/
• standards_as_opencode_skills: true - Convert standards to Skills
• profile: default - Which profile to use

Step 3: Install into Your Project

Navigate to your project directory and run the installation script:

cd /path/to/your/project
~/agent-os/scripts/project-install.sh

What gets installed:

• .opencode/command/ - 8 workflow commands
• .opencode/agent/ - 9 specialized agents
• .opencode/skills/ - 15 coding standard skills
• .opencode/workflows/ - 19 reusable workflow templates
• agent-os/ - Standards, product docs, and project config

---

What You Get

🎯 Commands (8)

Command	Description
/analyze-codebase	Analyze existing codebase and generate documentation
/plan-product	Plan product mission, roadmap, and tech stack
/shape-spec	Shape feature scope through targeted questions
/write-spec	Create comprehensive specification documents
/create-tasks	Generate strategic task breakdowns
/implement-tasks	Implement features with verification
/orchestrate-tasks	Multi-agent task orchestration
/improve-skills	Optimize skill descriptions for better discovery (run once after installation)

🤖 Agents (9)

Agent	Purpose	Model
codebase-analyzer	Codebase analysis & documentation	default
implementer	Feature implementation	default
implementation-verifier	End-to-end verification	default
product-planner	Product documentation	default
spec-initializer	Spec folder initialization	zai-coding-plan/glm-4.6
spec-shaper	Requirements gathering	default
spec-verifier	Spec validation	zai-coding-plan/glm-4.6
spec-writer	Specification writing	default
tasks-list-creator	Task list planning	default

📚 Skills (15)

Auto-loaded via opencode-skills plugin:

• Backend: API, migrations, models, queries
• Frontend: Accessibility, components, CSS, responsive
• Global: Coding style, commenting, conventions, error handling, tech stack, validation
• Testing: Test writing

Each skill references detailed standards in agent-os/standards/

⚠️ Important: Skills are initially created with basic descriptions that just point to standards files.

After first installation, run /improve-skills to:

• Rewrite skill descriptions for better OpenCode discovery
• Add "When to use this skill" sections with use-case examples
• Optimize descriptions with file types, situations, and triggers

This makes OpenCode more likely to proactively use the right skills at the right time.

---

Getting Started

1. Start OpenCode

cd your-project
opencode

2. Optimize Skills (First Time Only)

After your first installation, run:

/improve-skills

This improves skill descriptions so OpenCode can better discover and use them. Answer "all" when prompted.

Why this matters: The initial skill descriptions are basic. This command rewrites them with detailed use-cases, file types, and triggers so OpenCode knows exactly when to use each skill.

3. Follow the Workflow

For Existing Codebases:

Step 1: Analyze Your Codebase

/analyze-codebase

Creates: agent-os/product/tech-stack.md, agent-os/analysis/structure.md, patterns.md, summary.md

The analysis gives agents context about your existing code, patterns, and architecture.

Step 2: Define Product Vision (if needed)

/plan-product

Creates: agent-os/product/mission.md, roadmap.md, tech-stack.md

Step 3: Add a Feature

/shape-spec

• Agent asks clarifying questions about your feature
• Agents will read the analysis files to understand your codebase
• Suggests existing code to reuse based on detected patterns
• Example: "I see you use React Context, should we use that for auth state?"

Creates: agent-os/specs/[feature]/planning/requirements.md

Step 4: Write the Specification

/write-spec

Creates: agent-os/specs/[feature]/spec.md

Step 5: Break Into Tasks

/create-tasks

Creates: agent-os/specs/[feature]/tasks.md

Step 6: Implement

/implement-tasks

Builds the feature following your established patterns and tech stack.

For New Projects:

Step 1: Product Planning

/plan-product

Creates: agent-os/product/mission.md, roadmap.md, tech-stack.md

Step 2-6: Same as existing codebases (skip /analyze-codebase)

Example Workflow:

1. /analyze-codebase              ← Understand existing code ✅
2. /plan-product (if not done)    ← Define product mission & roadmap
3. /shape-spec                    ← "I want to add user authentication"
   → Agent asks questions, reads analysis
   → Suggests: "I see you use React Context, should we use that for auth state?"
4. /write-spec                    ← Generates formal spec
5. /create-tasks                  ← Breaks into implementation tasks
6. /implement-tasks               ← Builds the feature following your patterns

💡 Tip: Use /shape-spec to start planning your first feature. The agent will have full access to all the codebase analysis and will use it to make smart suggestions!

---

Workflow Overview

Codebase Analysis → Product Planning → Spec Shaping → Spec Writing → Task Creation → Implementation
     ↓                    ↓                 ↓              ↓              ↓              ↓
 tech-stack.md       mission.md     requirements.md   spec.md      tasks.md     verified code
 structure.md        roadmap.md
 patterns.md
 summary.md

Each phase creates structured markdown in agent-os/ for agent guidance. All subsequent agents have access to the analysis and product documentation.

---

Troubleshooting

❌ Skills not working?

Verify plugin installation:

cat ~/.config/opencode/opencode.json
# Should show: {"plugin": ["opencode-skills"]}

Check skills exist:

ls .opencode/skills/
# Should show 15 skill directories

Solution: Restart OpenCode to load the plugin

❌ Commands have no descriptions?

Verify frontmatter exists:

head -5 .opencode/command/plan-product.md
# Should show frontmatter with description

Solution: Reinstall

rm -rf .opencode agent-os
~/agent-os/scripts/project-install.sh

❌ Agents not delegating?

Check config:

cat agent-os/config.yml | grep use_opencode_agents
# Should show: use_opencode_agents: true

---

Configuration Options

Edit ~/agent-os/config.yml before installation:

# Install OpenCode commands?
opencode_commands: true

# Use OpenCode agents for delegation?
use_opencode_agents: true

# Convert standards to Skills (requires plugin)?
standards_as_opencode_skills: true

# Install generic commands folder?
agent_os_commands: false

# Which profile to use?
profile: default

---

Documentation & Resources

• OpenCode: https://opencode.ai/docs
• OpenCode-Skills Plugin: https://github.com/malhashemi/opencode-skills
• Anthropic Skills Spec: https://github.com/anthropics/skills
• Agent-OS Docs: https://buildermethods.com/agent-os

---

Updates

Read the changelog

Subscribe to be notified of major new releases of Agent OS

---

Credits

Original Creator

Created by Brian Casel @ Builder Methods, where Brian helps professional software developers and teams build with AI.

OpenCode Adaptation

This version has been adapted to work seamlessly with OpenCode and the opencode-skills plugin.