Building a Project Skeleton from Scratch with OpenSpec: Full Workflow Walkthrough

1. From Methodology to Practice

The previous article introduced the 2/8 rule, three‑step configuration, and six‑phase workflow. The core claim is that improving the tasks instruction text by 20% yields an 80% quality boost.

2. Explore: Clarifying Requirements

Using the /opsx:explore command, the AI runs a multi‑round dialogue to turn vague goals into concrete decisions. Key decisions captured:

Technology stack: React 19, TypeScript, Vite, Tailwind CSS, React Router.

Directory layout: default src/components/ vs. modular modules/ (the latter chosen).

MVP boundary: only the skeleton this iteration; tool registry postponed.

The AI records the decisions in proposal.md, confirming the change name project‑init and the goal of delivering a runnable skeleton with OpenSpec configuration pushed to GitHub.

3. Propose: Generating Five Artifacts

Running /opsx:propose creates the following files in openspec/changes/project‑init/:

proposal.md

design.md

specs/project‑scaffold/spec.md

review.md

tasks.md

The design.md translates the proposal into concrete implementation steps, e.g., using Home.tsx with Tailwind layout and a hard‑coded TypeScript tool array. The specs file lists seven requirements using the required ### Requirement: heading format. The review.md performs a five‑dimensional check (boundary conditions, rollback, test coverage, backward compatibility, task granularity) and flags a warning for task granularity because the review runs before tasks.md exists.

4. Apply: Executing Tasks

Executing /opsx:apply project‑init makes the AI read each artifact and run the listed steps in order. Highlights include:

Vite scaffold creation (handled via a temporary directory to avoid conflicts with existing .claude/ and openspec/ files).

Directory creation, tool‑registry interface, router setup with createBrowserRouter and RouterProvider, and component implementation.

Git initialization and GitHub push – the AI pauses when lacking GitHub credentials, prompting the user to run gh auth login and then continue.

Final build verification with tsc -b && vite build (99 ms, zero errors).

All 33 sub‑tasks across eight groups complete, and the AI reports Implementation Complete with a checklist of each step.

5. Browser Verification

Running npm run dev and opening http://localhost:5173 confirms three expectations: the home page shows "shuge AI Toolbox", the tools list displays "暂无工具" (no tools), and an unknown route renders a 404 fallback.

6. Archive

The /opsx:archive command moves the change directory to openspec/changes/archive/2026-05-11-project‑init/ and notes that no delta specs are needed for this first project.

7. Review and Lessons Learned

Key takeaways:

Explore is essential for surfacing hidden decisions before code generation.

Propose efficiently produces all required artifacts in a single pass.

Well‑crafted tasks.md (2‑5 minute steps, complete code and tests) turns the apply phase into deterministic execution rather than creative coding.

Initialization order matters: run npx create‑vite on an empty folder before openspec init to avoid Vite’s non‑empty‑directory error.

Configure GitHub CLI ( gh auth login) once; subsequent apply runs will push automatically.

The final project structure (shown in the image) includes the .claude/ tooling, OpenSpec configuration, and a clean React source tree.

8. Next Steps

The upcoming third episode will build the tool‑registry module (change name tool‑registry) to enable dynamic tool registration and routing. The repository for this tutorial is https://github.com/shuge-x/shuge-ai-toolbox.