name	implementation
description	Code generation skill that transforms spec-planning artifacts into production code. Implements development stories story-by-story with full context preservation, achieving 95%+ accuracy through systematic workflow and comprehensive context loading.
license	MIT
metadata	[object Object]

Implementation Skill v2.0

Systematic Code Generation from Specifications

Purpose

This skill transforms spec-planning artifacts into production-ready code through story-by-story implementation with comprehensive context preservation. Achieves 95%+ first-attempt accuracy by systematically loading all planning context before generating any code.

Key Features:

✅ Context-Driven Implementation - Loads ALL planning artifacts before coding
✅ Story-by-Story Execution - Incremental implementation with validation
✅ Test-First Development - Tests generated alongside production code
✅ Pattern Compliance - Follows architecture patterns from planning
✅ Hallucination Prevention - Never generates code without context
✅ State Management - Resume implementation at any story
✅ Quality Validation - Automated testing and standards compliance
✅ GitHub Integration - Synchronizes with GitHub issues from spec-planning

Foundation: Requires completed spec-planning skill output (Phase 5) AND a working Makerkit development environment.

Implementation Philosophy

See: Implementation Philosophy

This skill achieves 95%+ accuracy through a three-layer context system:

Layer 1: Standards (from architecture.md)

Tech stack, API patterns, database conventions, security patterns, testing patterns

Layer 2: Product (from prd.md + product-vision.md)

Feature requirements, user stories, business rules, success criteria

Layer 3: Specs (from data-models.md + ui-specifications.md + development-stories.md)

Exact table/field names, RLS policies, UI components, story acceptance criteria

The Golden Rule: Load ALL context first, reference continuously, never hallucinate.

When to Use This Skill

Activate this skill when you have:

✅ Completed spec-planning skill (all 5 phases)
✅ Development stories document ready
✅ spec_state.json exists with completed planning
✅ Makerkit development environment running
✅ Ready to start writing production code

Trigger Phrases:

"Implement the development stories from spec-planning"
"Generate production code for [project name]"
"Start implementation using planning artifacts"
"Begin coding from development stories"

Prerequisites:

Spec-planning skill completed (Phase 5)
All planning artifacts exist in 10 Projects/{project-name}/
spec_state.json shows current_phase = "completed"
Makerkit development environment ready

Makerkit Development Environment

See: Makerkit Setup Guide

Prerequisites:

✅ Makerkit repository cloned and running
✅ Dependencies installed via pnpm
✅ Supabase running locally (Docker)
✅ Development server accessible at localhost:3000

Verification:

# All checks must pass
pwd  # In next-supabase-saas-kit-turbo directory
docker ps | grep supabase  # Supabase containers running
pnpm run dev  # Server starts without errors

⚠️ If Makerkit not set up: Follow the complete setup guide before proceeding with implementation.

MCP Server Requirements

Required MCP Servers

None - This skill works without MCP servers

Optional MCP Servers

MCP Server	Purpose	Benefit	Fallback
GitHub	Update issue status, post comments	Real-time progress tracking	Manual `gh` commands via github-issue-manager skill
Supabase	Database migrations	Faster migration execution	Manual `pnpm` commands

MCP Server Detection

At initialization, skill detects available MCP servers and sets fallback strategies automatically.

Implementation Workflow Overview

3-Phase Implementation Process

Phase	Name	Duration	Outputs	Reference
1	Initialize Implementation	15-30 min	Context loaded, state initialized	Phase 1
2	Story-by-Story Implementation	Variable	Implemented stories	Phase 2
3	Final Validation	30-60 min	Build successful, tests passing	Phase 3

Total Time: Depends on story count (10 stories ≈ 3-5 hours, 20 stories ≈ 6-10 hours)

Quick Start

Starting New Implementation

User: "Implement development stories from spec-planning for Voice Bloom"

Claude:
1. Verifies spec-planning complete
2. Loads all context (architecture, PRD, data models, stories)
3. Initializes implementation state
4. Begins story-by-story implementation
5. Syncs with GitHub issues (if enabled)

Resuming Implementation

User: "Continue implementation for Voice Bloom"

Claude:
1. Loads existing impl_state.json
2. Displays progress (8/20 stories complete)
3. Reloads context
4. Continues from next story
5. Syncs with GitHub (if enabled)

Phase Workflows

Phase 1: Initialize Implementation

Objective: Load all context, verify prerequisites, set up implementation state Duration: 15-30 minutes See: Phase 1 Workflow

Loads all three context layers (Standards, Product, Specs), parses stories, initializes state, verifies Makerkit environment, and prepares for story-by-story implementation.

Key Steps:

Verify prerequisites (planning artifacts exist)
Load planning state (including GitHub issues)
Load context layers (architecture, PRD, data models, UI specs, stories)
Parse development stories
Initialize impl_state.json
Verify development environment
Display implementation preview

Validation Gate: All context loaded, state initialized, environment verified

Phase 2: Story-by-Story Implementation

Objective: Implement each story with full context, tests, and validation Duration: Variable (10-60 min per story) See: Phase 2 Workflow

Systematic 9-step loop for each story with full context loading, test-first development, and GitHub synchronization.

The 9-Step Story Loop:

Load Story Context - Get story details, update GitHub issue to "in-progress"
Verify Dependencies - Check prerequisite stories completed
Load Story-Specific Context - Assemble full context for story
Determine Implementation Mode - Choose Simple, Test-First, or Orchestrated
Generate Tests - Write test cases for acceptance criteria, update GitHub
Generate Production Code - Implement feature with full context, update GitHub
Run Tests & Validate - Execute tests, lint, type check, update GitHub
Commit Changes - Stage, commit, close/sync GitHub issue, update state
Report Progress - Display completion, move to next story

Implementation Modes:

Simple Mode (80% of stories): Direct implementation (~10-15 min)
Test-First Mode (15% of stories): Comprehensive TDD (~20-30 min)
Orchestrated Mode (5% of stories): Multi-agent (Claude Code only, ~15-20 min)

Full details: Implementation Modes

Phase 3: Final Validation & Deployment Prep

Objective: Comprehensive validation and readiness assessment Duration: 30-60 minutes See: Phase 3 Workflow

Runs full test suite, builds application, validates quality, closes GitHub planning issue, and prepares for QA validation.

Key Validations:

Full test suite passes (all stories)
Build successful
Type checking (no errors)
Lint checking (no critical errors)
Security patterns applied

Output: Implementation summary with stats, next steps, REQUIREMENT to run QA validation before deployment

Implementation Modes

See: Implementation Modes

Simple Mode (80% of stories)

Use for: Straightforward CRUD, simple UI, standard patterns Time: ~10-15 minutes per story

Test-First Mode (15% of stories)

Use for: Complex logic, calculations, critical security features Time: ~20-30 minutes per story

Orchestrated Mode (5% of stories)

Use for: Complex multi-file changes, system-wide refactoring (requires Claude Code) Time: ~15-20 minutes per complex story

Mode selection: Automatic based on story complexity, risk level, and file count.

Context Loading Reference

See: Context Loading Protocol

Always Load Before Each Story:

✅ architecture.md → API patterns, database conventions, security
✅ prd.md → Feature requirements for current story
✅ data-models.md → Exact table/field names story uses
✅ development-stories.md → Current story details
✅ spec_state.json → Patterns applied, GitHub integration status

Validation Checklist: Before generating ANY code, verify you can answer:

Do I know the exact table names?
Do I know the exact field names and types?
Do I know which API pattern to use?
Do I know which security patterns apply?
Do I know the acceptance criteria?

If ANY answer is unclear → STOP and load missing context

Hallucination Prevention Protocol

See: Hallucination Prevention

Core Rules

NEVER:

❌ Generate code without loading context first
❌ Guess table or field names
❌ Hallucinate API endpoints not in patterns
❌ Use packages not in tech stack
❌ Skip tests because "it's simple"

ALWAYS:

✅ Load all three context layers before coding
✅ Reference data-models.md for exact names
✅ Reference architecture.md for patterns
✅ Reference prd.md for requirements
✅ Generate tests before production code
✅ Ask for clarification if context unclear

Context Check Protocol: Pause before each file, verify context, use exact names.

State Management

See: State Management

Location: .claude/implementation/state/{project}/impl_state.json

Key Operations:

Initialize: Create new state at Phase 1
Load: Resume from existing state
Update: After each story (completed, test results, commits, GitHub status)
Complete: Mark implementation finished

State Schema: See Implementation State Template

GitHub Integration: State tracks story-to-issue mapping and issue status for synchronization.

Quality Assurance

See: Quality Assurance

Story Completion Criteria

A story is ONLY complete when ALL are met:

✅ All acceptance criteria satisfied
✅ Tests written and passing
✅ Code follows architecture patterns
✅ Database conventions applied correctly
✅ Security patterns applied
✅ Lint check passes
✅ Type check passes
✅ Code committed to git
✅ State updated
✅ GitHub synced (if enabled)

Validation: Run tests, lint, type check after each story. Fix issues immediately.

Error Handling

See: Error Handling

Common Error Types

Story Implementation Failure: Document, update state, request clarification or break into smaller stories Test Failure: Analyze cause (code bug, test bug, context mismatch), fix, re-run Build Failure: Identify failing file, fix errors, rebuild Missing Context: Stop, load missing information, never hallucinate

Recovery Strategies: Retry with more context, simplify and iterate, request human intervention, skip and continue

Integration with Spec-Planning

See: Spec Integration

Required Planning Artifacts

This skill consumes outputs from spec-planning Phase 5:

architecture.md → Vercel config, API patterns
data-models.md → Database schema with exact names
prd.md → Feature requirements
development-stories.md → Implementation instructions
spec_state.json → Patterns applied, decisions made, GitHub integration

How Artifacts Are Used:

architecture.md: API pattern for every endpoint, security for every feature
data-models.md: Exact field names for every query
prd.md: Requirements for every story
development-stories.md: Acceptance criteria for every test

Reference Files

Core Concepts (10 files)

Location: references/core/

Foundation concepts and system design:

Implementation Philosophy - Context problem and solution
Makerkit Setup - Environment setup and verification
Implementation Modes - Simple, Test-First, Orchestrated
Context Loading Protocol - How to load artifacts
Hallucination Prevention - Avoiding errors
State Management - State operations and resume
Quality Assurance - Completion criteria
Error Handling - Error recovery strategies
Spec Integration - Planning artifacts usage
Quick Start - Quick start guide and examples

Phase Workflows (3 files)

Location: references/phases/

Detailed step-by-step workflow instructions:

Phase 1: Initialize - Context loading, state initialization
Phase 2: Story Implementation - 9-step story loop
Phase 3: Final Validation - Comprehensive validation

Checklists (2 files)

Location: references/checklists/

Validation and quality checklists:

Context Loading Checklist - Context verification steps
Validation Checklist - Story completion validation

Workflows (1 file)

Location: references/workflows/

Specialized workflow procedures:

GitHub Sync Workflow - GitHub integration patterns

Templates (1 file)

Location: templates/

Reusable templates and configurations:

Implementation State Template - State file structure

Success Metrics

Implementation is successful when:

✅ All development stories completed
✅ 100% of acceptance criteria satisfied
✅ All tests passing (95%+ coverage)
✅ Build successful
✅ No type errors
✅ No lint errors
✅ Security patterns applied to all features
✅ Clean git history with logical commits
✅ GitHub issues closed (if integration enabled)
✅ Implementation state shows "completed"
✅ Context adherence: 0 hallucinations detected

Target Accuracy: 95%+ (code works correctly on first attempt)

Best Practices

Context Management

✅ Load once, reference continuously
✅ Verify before every file
✅ Never trust memory - always check docs

Code Generation

✅ Tests first - always
✅ Small increments - one story at a time
✅ Pattern compliance - follow architecture.md
✅ Exact names - use data-models.md character-for-character

Validation

✅ Validate after each story
✅ Run tests immediately
✅ Fix before proceeding

Git Workflow

✅ Logical commits - one story = one commit
✅ Clear messages - include story ID
✅ No broken commits - every commit builds and tests pass

Workflow Time Estimates

Per Story

Simple stories: 10-15 min (CRUD, basic UI)
Medium stories: 20-30 min (complex logic, integrations)
Complex stories: 30-60 min (multi-file, advanced features)

Full Implementation

10 stories: 3-5 hours
20 stories: 6-10 hours
50 stories: 15-25 hours

Time Savings vs Traditional:

Manual coding: 10x slower
AI without context: 5x slower (many iterations)
This skill: Optimal (95% accuracy first attempt)

Version History

v2.0.0 (2025-10-29):

Refactored to <500 lines with progressive disclosure
Organized 13 reference files + 1 template
Enhanced GitHub integration with issue synchronization
Added GitHub issue tracking throughout story loop
GitHub issue status updates at each step (in-progress, tests, code, validation, complete)
Automatic issue closing and vault sync on story completion
Story-to-issue mapping in impl_state.json
Fallback to github-issue-manager skill when MCP unavailable

v1.0.0 (2025-10-28):

Initial release
Story-by-story implementation with context preservation
Three-layer context system (Standards, Product, Specs)
Test-first development workflow
State management for resumable implementation
Hallucination prevention protocol
Quality validation gates
Git workflow integration
Support for Simple, Test-First, and Orchestrated modes

Version: 2.0.0 Last Updated: 2025-10-29 Maintained by: Personal Workflow Requires: spec-planning skill v2.0.0+ Workflow Mode: Orchestrated (Story-by-story execution)

Install Skill

SKILL.md