Workflow: Idea to Production
The complete development lifecycle for www.mavelpoint.com — from initial idea exploration through specification, implementation, testing, and production deployment. Powered by the OpenSpec artifact system and MavelPoint-specific skills.
Workflow Overview
Six phases drive every change from idea to production. The workflow is fluid — artifacts can be updated at any phase if new information emerges.
The Full Cycle
Every feature, fix, or refactor follows the same structured cycle.
Discover
Explore the problem space. Investigate the codebase. Compare approaches.
Plan
Start a change. Scaffold artifacts. Define the scope.
Specify
Create proposal, design, specs, and tasks artifacts.
Implement
Build the feature. Apply design tokens. Follow component patterns.
Verify
Test, review completeness, correctness, and coherence.
Ship
Sync specs, archive the change, deploy to production.
Key Principles
Rules that govern the entire workflow.
Fluid, Not Phase-Locked
If implementation reveals a design issue, update the design artifact immediately. Don't wait for a formal review cycle.
Agent-Driven
Claude Code can autonomously explore, plan, implement, test, and verify changes using the OpenSpec skill system.
Decision Preservation
Every change is archived with full artifacts. You can always trace back why something was built a certain way.
Testing as Specification
Tests are first-class artifacts created through the same workflow as features, with full specs and verification.
Phase 1: Discover
Explore the problem space before committing to a solution. Investigate, compare approaches, and surface risks.
openspec-explore
Thinking partner for investigating problems.
• Ask clarifying questions about the problem
• Investigate the codebase to map existing architecture
• Compare multiple approaches with tradeoff analysis
• Visualize concepts with ASCII diagrams
• Surface risks, unknowns, and assumptions
• Read existing OpenSpec proposals, designs, and specs
openspec-onboard
Guided introduction to the complete workflow cycle.
• Scans codebase for improvement opportunities (TODOs, missing tests, type issues)
• Walks through all phases with real codebase work
• Task selection and scope management
• Full cycle narration from explore to archive
Context Skills
Domain knowledge that informs discovery decisions.
mavelpoint-strategy
Company objectives, priorities, and roadmap
mavelpoint-audiences
User segments and persona profiles
mavelpoint-domain
Electronic music industry vocabulary
mavelpoint-web-product
Site architecture, sitemap, tech stack
Phase 2: Plan
Start a formal change. Scaffold the artifact directory and define what will be built.
openspec-new-change
Start a new change from scratch.
• Derive kebab-case change name
• Select workflow schema
• Create openspec/changes/<name>/
• Show artifact status and dependencies
openspec-ff-change
Fast-forward: create all artifacts at once.
• For well-understood features
• Bootstrap proposal + design + specs + tasks in one step
• Skips iterative artifact creation
openspec-continue-change
Resume an existing change at any phase.
• Pick up where you left off
• Check artifact completion status
• Works at any point in the cycle
Phase 3: Specify
Create the four core artifacts that define what will be built and how.
The Four Artifacts
Each artifact captures a different dimension of the change.
Why & What
• Problem or opportunity statement
• What will change
• New and modified capabilities
• Impact on the codebase
How & Decisions
• Current state and context
• Goals and non-goals
• Key technical decisions
• Tradeoffs and rationale
Detailed Requirements
• Precise requirement descriptions
• Scenarios in WHEN / THEN / AND format
• Testable and traceable
• Delta specs for incremental changes
Implementation Checklist
• Logically ordered task list
• Checkbox format for tracking progress
• Clear and focused scope per task
• Updated as work progresses
Web-Specific Design Skills
Skills consulted during the specification phase for web features.
mavelpoint-web-design
Design tokens, typography (Matter), colors, spacing, shadows, animations
mavelpoint-web-components
Component library, patterns, architecture (Astro + React islands)
mavelpoint-web-ux
User flows, navigation, conversion paths, 10 core journeys
mavelpoint-web-product
Sitemap, layouts, data sources, API endpoints, services
Brand & Content Skills
Skills that inform copy, messaging, and visual identity during specification.
mavelpoint-brand
Voice, tone, visual identity, scene-native language
mavelpoint-tokens
Design token values, CSS custom properties, Tailwind config
mavelpoint-copy
Copywriting framework, headline formulas, CTA patterns
mavelpoint-content
Content marketing, blog strategy, SEO
mavelpoint-growth
Growth strategy, funnels, metrics
mavelpoint-ads
Ad campaigns, paid channels, targeting
Phase 4: Implement
Build the feature by working through the task checklist. Code changes follow the design and spec artifacts.
openspec-apply-change
The core implementation skill.
• Read context: proposal, design, specs, tasks
• Show current progress (N/M tasks complete)
• Loop through each task:
→ Announce task being worked on
→ Make focused code changes
→ Mark task complete: - [ ] → - [x]
• Handle blockers: clarifications, design issues, errors
• Update artifacts if design issues emerge (fluid workflow)
openspec-document
Document existing code as specifications (reverse engineering).
• Read ALL source files before writing specs
• Extract controller endpoints, DTOs, entities, repository methods
• Capture business logic from use cases
• Verify accuracy before committing
• Only document code that EXISTS — never invent
Web Tech Stack
Technologies used during implementation of web features.
Astro 5 SSR
Static content via .astro components. Zero client JS for non-interactive pages.
React 18 Islands
Interactive components with client:idle, client:visible, client:load directives.
Tailwind CSS 3.4
Custom design tokens. Matter font. Dark mode by default. Mobile-first.
Nanostores
Cross-component state. Player, tabs, navigation, collections persist across ViewTransitions.
Headless UI
Dialog, Disclosure, Popover, Listbox. Accessible unstyled interactions.
Framer Motion
React island animations. Entrance/exit, scroll triggers, AnimatePresence.
Phosphor Icons
6 weight variants: thin, light, regular, bold, fill, duotone.
Keen Slider
Performant carousels with touch support. Custom wrapper component.
Phase 5: Verify
Test the implementation and verify it matches the specifications before shipping.
openspec-test
Create unit tests following established patterns.
• Parse module path: context/module
• Read unit-testing-guide.md for patterns
• Implement tests in complexity order:
1. Use cases (simplest)
2. Repositories (mock PrismaService)
3. Controllers (mock services)
4. Services (most complex)
• Target: >90% coverage
• Tests tracked as formal OpenSpec specs
openspec-verify-change
Verify implementation matches all artifacts.
Three verification dimensions:
Completeness
All tasks checked off. All spec requirements implemented.
Correctness
Code evidence maps to requirements. Scenarios covered by tests.
Coherence
Design decisions followed. Project conventions respected.
Issue Priority Levels
Verification groups issues into three severity tiers.
Critical
Incomplete tasks, missing requirements. Blocks archive.
Warning
Spec divergences, missing scenarios. Should fix before shipping.
Suggestion
Pattern inconsistencies, minor improvements. Nice to have.
Phase 6: Ship
Finalize the change, sync specifications, archive decision history, and deploy to production.
openspec-sync-specs
Sync delta specs to main specification files.
• Find delta specs in openspec/changes/<name>/specs/
• Intelligent merging (not simple copy):
→ ADDED requirements: add to main spec
→ MODIFIED: apply partial updates
→ REMOVED: delete from main
→ RENAMED: rename in main
• Create new spec files if capability is new
• Preserve existing content not mentioned in delta
openspec-archive-change
Archive the completed change and deploy.
• Check artifact and task completion
• Optionally sync specs to main (if not done)
• Move change to openspec/changes/archive/YYYY-MM-DD-<name>/
• Display summary of archived artifacts
• Decision history preserved for future reference
Deployment Infrastructure
How the web codebase reaches production.
Astro SSR on Node
Astro 5.x with @astrojs/node adapter (standalone mode). Server-rendered pages with hybrid static + dynamic routes.
Azure Deployment
Hosted on Azure infrastructure. Environment variables for API URLs, storage, Gemini keys, and feature flags.
Partytown
Third-party analytics scripts (GA, GTM, Meta Pixel, TikTok, Spotify) offloaded to web workers.
Sentry
Error tracking and monitoring in production. Captures client-side and server-side errors.
Complete Skill Map
All skills referenced throughout the workflow, organized by category.
OpenSpec Workflow Skills
The artifact-driven development cycle that powers every change.
| Skill | Phase | Purpose |
|---|---|---|
| openspec-explore | Discover | Investigate problems, compare approaches |
| openspec-onboard | Discover | Learn the workflow, guided walkthrough |
| openspec-new-change | Plan | Start a new change, scaffold artifacts |
| openspec-ff-change | Plan | Fast-forward all artifacts at once |
| openspec-continue-change | Plan | Resume work on existing change |
| openspec-apply-change | Implement | Execute tasks, build the feature |
| openspec-document | Implement | Reverse-engineer existing code into specs |
| openspec-test | Verify | Create unit tests, target >90% coverage |
| openspec-verify-change | Verify | Check completeness, correctness, coherence |
| openspec-sync-specs | Ship | Merge delta specs into main specs |
| openspec-archive-change | Ship | Archive completed change with full history |
MavelPoint Web Skills
Web-specific design, component, and architecture knowledge.
| Skill | Used In | Purpose |
|---|---|---|
| mavelpoint-web-product | Discover, Specify | Sitemap, tech stack, layouts, data sources, services |
| mavelpoint-web-design | Specify, Implement | Design tokens, Matter font, colors, spacing, animations |
| mavelpoint-web-components | Specify, Implement | Component library, patterns, Astro + React architecture |
| mavelpoint-web-ux | Specify, Implement | User flows, navigation, conversion paths |
Brand & Strategy Skills
Cross-cutting knowledge that informs decisions at every phase.
| Skill | Purpose |
|---|---|
| mavelpoint-strategy | Company objectives, priorities, and 2026 roadmap |
| mavelpoint-brand | Voice, tone, visual identity, scene-native language |
| mavelpoint-tokens | Design token values, CSS properties, Tailwind config |
| mavelpoint-audiences | User segments, persona profiles, audience tiers |
| mavelpoint-copy | Copywriting framework, headline formulas, CTA patterns |
| mavelpoint-content | Content marketing, blog strategy, SEO |
| mavelpoint-growth | Growth strategy, funnels, conversion metrics |
| mavelpoint-ads | Ad campaigns, paid channels, targeting |
| mavelpoint-domain | Electronic music industry glossary and vocabulary |