supabase-postgres-best-practices/IMPLEMENTATION_GUIDE.md

# Supabase Skills Package - Implementation Guide

## Status: Phase 1 Complete ✅

This guide breaks down the Supabase skills package implementation into manageable, iterative tasks.

---

## ✅ Completed So Far

### 1. Planning Phase (Complete)
- Explored postgres-best-practices structure, supabase-js codebase, and skill-creator guidelines
- Designed unified build system supporting multiple skill types
- Created comprehensive plan at [.claude/plans/immutable-scribbling-galaxy.md](.claude/plans/immutable-scribbling-galaxy.md)

### 2. Build System Refactor (Complete ✅)
- ✅ Created feature branch `feature/supabase-skill`
- ✅ Renamed `packages/postgres-best-practices-build` → `packages/skills-build`
- ✅ Created subdirectories `src/postgres/` and `src/supabase/`
- ✅ Moved postgres files to `src/postgres/`
- ✅ Updated BUILD_DIR path in postgres/config.ts
- ✅ Updated type imports in postgres module files
- ✅ Extended shared types (SkillConfig, SkillType, Resource)
- ✅ Created skills-config.ts registry
- ✅ Created CLI interface (cli.ts)
- ✅ Updated package.json scripts to use CLI
- ✅ Verified postgres build works with new system
- ✅ Committed all changes (commit: 345b560)

---

## ✅ Completed Tasks (Phase 1)

All tasks 1-6 have been completed successfully! The unified build system foundation is now in place.

### Task 1: Complete Postgres Module Updates ✅
- Tested postgres build after refactoring
- Added temporary build:postgres script
- Verified AGENTS.md generation works correctly

### Task 2: Extend Shared Types ✅
- Added SkillConfig, SkillType interfaces
- Added Resource, ReferenceParseResult for reference-based skills

### Task 3: Create Skills Configuration ✅
- Created src/skills-config.ts registry
- Defined postgres-best-practices and supabase configs

### Task 4: Create Basic CLI Interface ✅
- Created src/cli.ts with validate/build commands
- Added support for --skill flag to target specific skills

### Task 5: Update package.json ✅
- Renamed package to "skills-build"
- Updated all scripts to use new CLI
- Added skill-specific scripts (build:postgres, build:supabase, etc.)

### Task 6: Commit Build System Refactor ✅
- Committed all changes (commit: 345b560)
- Verified postgres build still works

---

## 🚧 Next Steps (Phase 2: Supabase Module)

You're now ready to create the supabase module! The next phase focuses on building the reference-based skill system.

## 📦 Tasks 7-12: Create Supabase Module

After completing tasks 1-6, you'll be ready to create the supabase module. Here's a preview:

### Task 7: Create Supabase Config
**File:** `packages/skills-build/src/supabase/config.ts`
- Similar to postgres/config.ts
- Define paths for supabase skill

### Task 8: Create Supabase Parser
**File:** `packages/skills-build/src/supabase/parser.ts`
- Parse markdown reference files
- Extract headings, code blocks, "Incorrect"/"Correct" patterns

### Task 9: Create Supabase Validator
**File:** `packages/skills-build/src/supabase/validate.ts`
- Validate reference file structure
- Check for required sections

### Task 10: Create Supabase Builder
**File:** `packages/skills-build/src/supabase/build.ts`
- Read all reference files from references/
- Generate AGENTS.md

### Task 11: Update CLI for Supabase
**File:** `packages/skills-build/src/cli.ts`
- Import supabase module
- Add supabase to build/validate logic

### Task 12: Test Unified Build System
```bash
npm run build  # Should build both skills
npm run validate  # Should validate both skills
```

---

## 📝 Task 13-20: Create Supabase Content (Final Phase)

After the build system is complete, create the actual supabase skill content:

1. Create `skills/supabase/` directory structure
2. Write SKILL.md, metadata.json, README.md
3. Create `references/supabase-js.md` (hub file)
4. Create 7 sub-resource files in `references/supabase-js/`:
   - client-lifecycle.md
   - error-handling.md
   - auth-patterns.md
   - database-queries.md
   - realtime-subscriptions.md
   - storage-operations.md
   - common-mistakes.md
5. Test skill loading and progressive disclosure

---

## 🎯 Quick Reference Commands

```bash
# Navigate to build package
cd packages/skills-build

# Install dependencies
npm install

# Build postgres only
npm run build:postgres

# Build all skills
npm run build

# Validate postgres only
npm run validate:postgres

# Validate all skills
npm run validate

# Check status
git status

# Commit progress
git add .
git commit -m "your commit message"
```

---

## 📋 Success Criteria for Phase 1

- ✅ Postgres build still works after refactoring
- ✅ Unified build system can build postgres
- ✅ CLI interface works for postgres
- ✅ No regressions in postgres AGENTS.md generation
- ✅ Code is committed to feature branch

---

## 📚 Resources

- **Full Plan:** [.claude/plans/immutable-scribbling-galaxy.md](.claude/plans/immutable-scribbling-galaxy.md)
- **Postgres Build System:** `packages/skills-build/src/postgres/`
- **Current Branch:** `feature/supabase-skill`

---

## 💡 Tips

1. **Test frequently**: Run `npm run build:postgres` after each change
2. **Commit often**: Small commits make it easier to track progress
3. **One task at a time**: Complete tasks 1-6 before moving to supabase module
4. **Ask for help**: If stuck, refer back to the full plan or ask questions

---

## Next Session Starting Point

When you're ready to continue:

1. Start with **Task 7: Create Supabase Config** (Phase 2)
2. Work through tasks sequentially (7 → 8 → 9 → ...)
3. Test after each task
4. Commit progress regularly

Phase 1 is complete! The unified build system is now ready for the supabase module implementation. 🚀