Practicing AI Specs with OpenSpec and OpenCode: A Step-by-Step Tutorial

The article demonstrates AI-assisted development using OpenSpec combined with OpenCode, building a real-time fund valuation desktop application as a practical tutorial. OpenSpec is an open-source, tool-agnostic specification framework that integrates with 22+ AI coding assistants, avoiding vendor lock-in. OpenCode is also open-source, supports multiple LLM providers, and requires no paid subscription.

Project Planning

Instead of writing extensive requirement documents for a personal project, the author uses OpenCode's plan mode or OpenSpec's explore command to generate a task plan. Requirements are derived by observing existing fund apps and listing desired features:

App target: real-time fund valuation, A-share/US/HK market data.

Three menus: Refresh (fund management), Fund (details), Market (quotes).

Refresh: manual add/edit/delete funds, Alipay screenshot recognition, show daily gain/holding gain, auto-refresh every 1s, pull-to-refresh, click fund to navigate to Fund menu.

Fund: real-time valuation chart, performance history, personal returns, holdings with real-time stock quotes.

Market: standard securities app view for A-share, US, HK indices; desktop app (not mobile).

Technical stack decisions are made upfront: Tauri for desktop framework, akshare (GitHub: akfamily/akshare) for free financial data APIs.

UI Design with Pencil

To avoid lengthy UI tweaking, the author uses Pencil (an MCP-enabled UI design platform) via its VS Code extension. After registering and enabling MCP in Pencil settings, restarting OpenCode auto-connects to Pencil's MCP server. The requirements are pasted into OpenCode in Plan mode, then switched to Build mode to generate UI designs previewable in VS Code.

Understanding OpenSpec

Install OpenSpec globally: npm install -g @fission-ai/openspec@latest. Install the VS Code extension OpenSpecCodeExplorer. Run openspec init in the project to bind OpenCode, creating .openspec directory and AGENTS.md.

OpenSpec directory structure:

openspec/
├── AGENTS.md          # AI assistant usage guide (auto-generated)
├── project.md         # Project-specific context (tech stack, conventions)
├── specs/             # Authoritative baseline: current deployed capabilities
│   └── [capability]/
│       ├── spec.md    # Requirements & scenarios
│       └── design.md  # (optional) Technical implementation patterns
├── changes/           # Proposals: active work in progress
│   └── [change-name]/
│       ├── proposal.md # Background, core content, impact assessment
│       ├── tasks.md    # Implementation task checklist
│       ├── design.md   # (optional) Architecture decision record
│       └── specs/      # Incremental spec changes (ADDED/MODIFIED/REMOVED)
└── archive/           # Completed changes history

OpenSpec adds commands under .opencode/command. Key commands (phase-ordered): /opsx:explore – Exploration mode: think, research, clarify requirements. /opsx:new – Start a new change using experimental artifact workflow. /opsx:continue [change-name] – Resume previous change, create next artifact. /opsx:ff – One-shot: create change and generate all implementation files. /opsx:apply – Execute tasks from tasks.md (coding phase). /opsx:verify [change-name] – Verify implementation matches change artifacts. /opsx:sync – Sync changed specs to main spec baseline. /opsx:archive – Archive completed change. /opsx:bulk-archive – Archive multiple changes. /opsx:onboard – Launch onboarding flow.

CLI commands (setup, browsing, validation, lifecycle, workflow, schemas, config, utility) are also listed but not used in this tutorial.

OpenSpec separates concerns: Command guides AI collaboration (planning/executing specs), Skill tells AI how to perform specific tasks.

Experiencing OpenSpec: Three-Phase Workflow

Phase 1: Create Change (Proposal)

OpenSpec enforces alignment on "what" and "why" before "how". Steps:

Identify requirement (new feature, refactor, architecture shift).

Scaffold unique directory under openspec/changes/<change-id>/.

Define incremental specs (add/modify/remove) for affected capabilities.

Create tasks.md with verifiable steps.

Validate proposal structure with openspec validate.

Start with /opsx:explore 创建项目架构 (or just /opsx:explore). The command essentially injects the opsx-explore.md prompt. Paste the requirements, let AI refine them, then proceed.

If context grows too large, resume with /opsx:continue [change-name] which restores state from tasks.md.

Create artifacts sequentially:

Proposal: 描述这个变更的内容，我来帮你起草 proposal.md Design & Specs in parallel: 同时创建 design、specs Task list: 创建任务清单 After completion, openspec/changes/{feature} contains proposal.md, design.md, specs/, tasks.md.

Phase 2: Implementation

AI loads context from proposal.md and specs, executes tasks.md sequentially, marking tasks done in real-time. Resume anytime with /opsx:continue [change-name].

Run /opsx:apply to start coding (unattended). After completion, run /opsx:verify [change-name] to check correctness and consistency. If minor fixes needed, ask AI in same conversation. For major logic/design changes, use /opsx:sync to update the change artifacts.

Phase 3: Archive (Integration)

Run /opsx:archive to mark feature complete. OpenSpec CLI moves the change folder to openspec/changes/archive/ and merges spec increments (ADDED/MODIFIED) into openspec/specs/, keeping the authoritative baseline current and reducing retrieval overhead.

The author notes the initial architecture spec omitted Ant Design and Pencil design integration; these can be added in subsequent small changes. The article advocates incremental, single-module changes ("small steps, fast iterations").

Next Steps

Remaining features to implement via separate specs:

Implement UI per Pencil designs.

Fund management module.

Fund detail view module.

Market quotes module.

Each feature follows the same three-phase OpenSpec workflow.