Technology Selection

This section describes key technology choices required for implementing specification-driven workflows.

LLM Service Provider

Primary: Claude Code

Claude Code is the primary LLM service provider. It natively supports CLAUDE.md and project guidance files, enabling agents to effectively consume structured context. Built-in MCP (Model Context Protocol) support allows flexible tool capability extension. Claude Code excels at core development tasks like code generation, refactoring, and bug fixing, while providing enterprise-grade security and privacy protection. For high-frequency development scenarios, Pro/Max subscriptions offer "all-you-can-eat" capacity without worrying about API call limits. The overall ecosystem integrates well with OpenSpec, various IDE extensions, and other tools.

Alternative: OpenCode

When Claude Code is unavailable (e.g., network restrictions, cost considerations), OpenCode can serve as an alternative.

OpenCode is an open-source project that can be self-deployed without vendor lock-in concerns. It supports multiple LLM backends, allowing use of local models or lower-cost APIs, with data remaining entirely in your local environment.

Selection Guide:

• Enterprise environment, need best quality → Claude Code
• Network restrictions or compliance requirements → OpenCode (local deployment)
• Cost-sensitive experimental projects → OpenCode
• Need specific model fine-tuning → OpenCode
• Unsure → Claude Code (safer choice)

Specification Framework: OpenSpec

Why a Framework

When teams start adopting AI-assisted development, they quickly discover a problem: AI needs specifications, but specs are scattered everywhere. Some are in Confluence, others in Google Docs, some buried in Jira tickets. Each team invents their own format, and AI agents must re-learn the structure every time.

Change tracking is even messier. When a feature spans three months of development with five spec revisions along the way, no one can definitively say what the current specification actually is. Implementation drifts from spec until one day they're completely disconnected.

OpenSpec solves this: it gives specifications a permanent home, a unified format, and a clear lifecycle. AI agents know where to find specs, how to parse them, and how to track changes. Humans can finally answer the simple question: "Where is the spec for feature X?"

Architecture

openspec/
├── project.md              # Project conventions and context
├── specs/                  # Current truth - what IS built
│   └── [capability]/
│       └── spec.md         # Requirements and scenarios
├── changes/                # Proposals - what SHOULD change
│   └── [change-id]/
│       ├── proposal.md     # Why, what, impact
│       ├── tasks.md        # Implementation checklist
│       └── specs/          # Delta changes per capability
└── archive/                # Completed changes (historical)

Simply put: specs/ holds current truth (what's already built), changes/ holds proposals (what should change), and archive/ holds history (what was changed).

CLI Quick Reference

# Discovery
openspec list                    # Active changes
openspec list --specs            # Current capabilities
openspec show [item]             # View details

# Validation
openspec validate [change] --strict

# Lifecycle
openspec archive [change] --yes  # Complete and merge

Framework Transition Strategy

OpenSpec specifications are plain Markdown with no proprietary format. Heading structures follow fixed conventions, making them parseable by any text processing tool. All content is stored in Git, preserving complete history during migration.

If you need to switch frameworks in the future, the content requires no significant rewriting.

Technology Stack Overview

Layer	Primary	Alternative
LLM Service	Claude Code	OpenCode
Spec Framework	OpenSpec	Plain Markdown + Git
API Spec	Any schema-based API description format (choose based on project needs)	-
Spec Format	Gherkin (OpenSpec adopts, BDD convention)	-
Version Control	Git	-
Document Format	Markdown	-

Why is no specific API spec format recommended?

Choose API specification format based on project needs. The key is adopting a schema-based description that enables AI agents to accurately understand API structure. Common options include OpenAPI, AsyncAPI, GraphQL Schema, etc.

Agent Skill Framework

Why Skill Frameworks Matter

AI coding agents lack inherent discipline—they don't automatically clarify requirements, write tests first, or verify results before claiming completion. A skill framework provides "an employee handbook for AI agents," enforcing professional development practices through structured workflows.

Without explicit process discipline, agents skip steps, rationalize shortcuts, and claim completion prematurely. Skill frameworks convert implicit team knowledge into explicit, enforceable workflows.

Recommendation: Superpowers

Repository: github.com/obra/superpowers

Superpowers is a composable skill framework that guides AI agents through disciplined development workflows. Rather than advisory suggestions, it enforces mandatory processes from requirements clarification through verification. The framework provides 15 structured skills covering the complete development lifecycle.

Key Skills for Our Workflows

Skill	Aligns With	Purpose
Brainstorming	Feature Development Flow	Socratic questioning before coding; YAGNI enforcement
Writing Plans	API Design Flow	Detailed implementation tasks (2-5 min each)
Systematic Debugging	Bug Fix Flow	4-phase investigation: root cause → pattern → hypothesis → fix
Test-Driven Development	Principle E4 (Verification)	RED-GREEN-REFACTOR enforcement
Verification Before Completion	Principle E4 (Verification)	Evidence-based completion claims

Integration with OpenSpec

Superpowers complements OpenSpec: OpenSpec defines what to build (specifications), while Superpowers defines how agents should work (process discipline). Teams use both together—OpenSpec for specification lifecycle, Superpowers for execution discipline.

For detailed adoption guidance, see the Agent Skill Adoption proposal.

References

• Claude Code - Official Claude Code documentation
• OpenCode - OpenCode open source project
• OpenSpec - Official OpenSpec repository
• Superpowers - Agent skill framework for disciplined development
• Model Context Protocol (MCP) - Anthropic's protocol for AI-tool integration