From Chaos to Order: Building a Spec-Driven AI Collaboration System with OpenSpec & AI Workflows

Background and Motivation

The author worked on a Vue 3.5 + TypeScript + Pinia + Vant 4 retail H5 project and found that AI-assisted coding faced recurring problems in brownfield incremental development: AI forgot project conventions between sessions, reinvented existing components, ignored i18n rules, and broke existing logic when adding features. The core issue was not AI's coding ability but how to give it persistent, structured project context.

Specification-Driven vs. Conversational Development

The article contrasts conversational AI development (natural language, ephemeral context, inconsistent outputs) with specification-driven development (structured proposal/design/tasks documents, version-controlled, reproducible). Key differences:

Input : Conversational uses natural language; specification-driven uses structured proposal + design + tasks.

Traceability : Conversational chat logs are hard to trace; specification-driven uses versioned documents committed with code.

Consistency : Conversational results vary per session; specification-driven yields consistent output given same spec and skills.

Complexity handling : Conversational works for simple tasks but collapses on complex ones; specification-driven handles complexity via task decomposition.

Knowledge reuse : Conversational leaves experience in chat logs; specification-driven distills experience into reusable skills.

The bottleneck in AI-assisted coding is not code generation capability but how context is delivered . Conversational development is "instant delivery" — each session starts from zero, context passed orally. Specification-driven development is "structured injection" — project knowledge encoded into data structures AI can understand, loaded on demand, written once, effective permanently.

System Architecture: OpenSpec + AI Workflows

The system has two decoupled layers:

OpenSpec (Specification Layer)

Manages each change via three Markdown files under openspec/changes/<feature>/: proposal.md (WHY/WHAT): business context, goals, acceptance criteria. design.md (HOW): architecture, APIs, components, data flow. tasks.md (DO): prioritized, dependent task breakdown for AI execution.

AI Workflows (Execution Layer)

Directory ai-workflows/ containing: workflows/ — four scenario definitions: feature-development.md, bug-fix.md, hotfix.md, refactor.md. skills/ — 33 skills in four categories:

project (8): e.g., vue3-component, api-service, i18n, style.

business (19): e.g., retail-ordering, home-page, vivo-plus-coupon, whole-discount.

workflow (4): e.g., cross-module, new-change.

quality (2): code-review, regression-test.

Each skill is a SKILL.md with applicability keywords, step-by-step workflow, non-applicability rules, and a mandatory checklist. hooks/ — 17 passive triggers configured in config.yaml: before-message (6): e.g., recommend-workflow, ensure-user-review. skill-loaded (2): initialize skill context. after-edit (3): e.g., auto-format-code, run-linter. after-message (3): logging, state updates. templates/ — Vue, API, Store, i18n scaffolds. schemas/ — data structure definitions.

Component Interaction Flow

End-to-end flow for a new feature:

User describes need → recommend-workflow hook suggests feature-development workflow.

AI reads workflow steps, uses templates to create OpenSpec trio ( proposal, design, tasks). ensure-user-review hook blocks code generation until user confirms the spec.

User approves → AI loads relevant business skills (e.g., retail-ordering) and project skills (e.g., vue3-component) to implement tasks sequentially. after-edit hooks auto-format and lint each change.

All tasks done → change archived.

Multiple skills collaborate: e.g., retail-ordering provides domain context, vue3-component enforces component patterns, i18n ensures translation reuse.

Case Study: vivo+ Coupon Feature

Requirements

Add vivo+ points coupons to retail order confirmation page: entry in whole-order discount area, modal for 2×/5× coupon selection, per-SKU binding, serial-number (IMEI) vs. non-serial product handling, mutual exclusion with existing promotions, auto-clear on member/source change. Involved 10+ files across components, store, API, types, i18n.

Specification Phase

AI, armed with retail-ordering skill, located WholeDiscount.vue, ProductInfo.vue, enumerations, and generated the three spec docs with 15 tasks. Two notable moments:

API mid-stream change : Backend consolidated multiple endpoints into one accepting skuCodeList. Author told AI once; AI updated design.md and precisely modified three code locations (API signature, caller, types) — no extra files touched because design.md mapped impact scope.

Zero duplicate i18n keys : AI followed i18n skill: scan zhLang.ts first, only add missing keys using project naming convention (camelCase, semantic, grouped), then reference via getLanguage().

Implementation Phase

Key decisions driven by skills:

Architecture alignment : vue3-component skill rule "check similar existing components first" made AI study OfficialWebsite.vue and refactor the coupon logic into a self-contained VivoPlusCoupon.vue (entry, list, modal, store updates) instead of scattering logic in the parent.

Serial vs. non-serial branching : retail-ordering skill documented ImeiControlFlagEnum and IMEI verification flow; AI coded the correct branch from the start, avoiding a missing-scenario bug.

Figma fidelity : MCP tool fed exact design tokens (spacing, font, color) to AI, eliminating guess-and-check cycles.

Quantitative Results

12 acceptance criteria all passed; 15 tasks executed.

10+ files created/modified.

0 duplicate i18n keys. retail-ordering skill grew 13 sub-skills, reusable for future work in the same module.

Collaboration Experience Shift

Before: "correction mode" — 80% effort finding AI errors, 20% on business. After: "confirmation mode" — 20% reviewing direction, 80% on business. AI role shifted from "junior needing supervision" to "trusted senior developer". Each session starts from accumulated project knowledge, not zero.

Continuous Improvement Practices

From Incidents to Skills

An i18n incident (hard-coded Chinese text + duplicate key) produced the i18n skill with four rules: check zhLang.ts → reuse → add per convention → reference via getLanguage(). Pattern: incident → rule → skill → permanent fix .

Skill Iteration Example: vue3-component

v1: basic generate steps.

v2: added "non-applicable scenarios" (pure CSS → project/style; copy-only → direct edit; store changes → vue3-store) after AI over-engineered a button color change.

v3: added mandatory checklist (i18n via $t(), reuse fullscreen dialog, no any types) after AI missed translations.

Principle: keep skills 100–150 lines; split if longer; prune obsolete content.

Hooks That Prevented Accidents

ensure-user-review

blocked AI from creating proposal.md and editing source files when author only floated an idea without confirmation — saved ~30 min rollback. after-edit/auto-format-code ran Prettier + ESLint --fix on a messy generated method, fixing indentation, unused imports, naming inconsistency before code review.

Two-Week Adoption Guide

Week 1: Minimum Viable Setup

Create directory structure per §3.2.

Write first project skill targeting highest-pain, clear-rule area (author chose i18n).

Configure ensure-user-review hook.

Write AGENT.md telling AI how to use the system.

Validate with a tiny real change (e.g., 4-digit → 6-digit SMS code); verify skill loading, spec generation, hook firing.

Week 2: First Full Feature & Team Enablement

Pick a real but non-urgent 5+ file feature; run full feature-development flow (proposal → design → tasks → review → implement) without shortcuts.

Log every "if only AI knew X" moment; convert to business skills or checklist items (author extracted retail-ordering, vivo-plus-coupon, whole-discount).

Harden: ensure four core project skills (component, API, i18n, store) are complete; add after-edit format/lint hooks (30 min setup, saves 10–15 min/day); write 1-page team README.

Measured Outcomes

AI understanding accuracy : ~60% → ~90% (less rework).

Knowledge reuse : Skills persist across features & sessions.

Code quality : Hooks auto-catch low-level errors.

Newcomer onboarding : Read skills to learn project conventions.

Future Directions

Auto-extract experience into skills after task completion.

Package project/ skills as cross-project reusable modules.

Explore skill sharing across same-stack projects.

Instrument skill usage for data-driven iteration.

Appendix: Tech Stack & FAQ

Stack: Vue 3.5, <script setup>, TS 5.x, Vite 6, Pinia 3, vue-i18n 11, Vant 4, TailwindCSS 3, pnpm, ESLint 9, Vitest.

FAQ highlights: 1–2 days initial setup; value compounds from 4th feature; suited for 10+ page multi-person projects; skills are Markdown — easy to update; differs from RAG by adding active orchestration ("what to do now" vs. "where is knowledge").