Skip to content

WORKFLOW.md

Latest commit

 

History

History
439 lines (320 loc) · 10.9 KB

WORKFLOW.md

File metadata and controls

439 lines (320 loc) · 10.9 KB

Development Workflow

SDK Kit's Spec-Driven Development Process

This document describes how we plan, track, and implement features in SDK Kit.

Overview

We use a spec-driven workflow that combines:

  • Specs (in specs/) - Detailed specifications, living in the repository
  • GitHub Issues - Tracking and assignment
  • Milestones - Progress tracking by phase

Key principle: Specs are the single source of truth. Issues link to specs, not the other way around.

The Process

1. Spec → 2. Tasks → 3. Issues → 4. Implementation → 5. Review

1. Create Specification

For each major feature or phase, create a spec directory:

specs/phase-X-feature-name/
├── spec.md       # What we're building (vision, goals, scope)
├── plan.md       # How we'll build it (detailed implementation)
├── tasks.md      # Ordered task breakdown with dependencies
└── contracts/    # API contracts, type definitions

Example: specs/phase-1-core-sdk/

Key sections:

  • spec.md - High-level vision, goals, success criteria, scope
  • plan.md - Technical details, file-by-file breakdown, patterns
  • tasks.md - Dependency-ordered tasks with [P] markers for parallel work

2. Break Down Tasks

In tasks.md, document:

  • Task numbering (dependency order)
  • Dependencies between tasks
  • Parallel execution markers [P]
  • File paths to create/modify
  • Acceptance criteria per task
  • Time estimates

Format:

### Task #1: Define TypeScript Types

**Depends on:** None
**Blocks:** Tasks #2-5
**Estimate:** 2-3 hours
**Can run in parallel:** No

#### Files to Create
- types/plugin.types.ts
- types/sdk.types.ts

#### Acceptance Criteria
- [ ] All types export from index.ts
- [ ] TypeScript compiles with strict mode
- [ ] No `any` types in public APIs

3. Create Milestone + Issues

Create Milestone:

# Using the helper script (recommended)
./scripts/create-milestone.sh "Phase X: Name" "Brief description"

# Or with due date
./scripts/create-milestone.sh "Phase X: Name" "Brief description" "2025-12-31"

# Or manually via gh CLI
gh api repos/prosdevlab/sdk-kit/milestones --method POST \
  --field title="Phase X: Name" \
  --field description="Brief description" \
  --field state="open"

Create Issues:

For each task in tasks.md, create a GitHub issue:

Title: [Task Name from tasks.md]

Description:
📋 **Spec:** specs/phase-X-feature/tasks.md#task-N

[Brief description]

**Files to create/modify:**
- path/to/file.ts
- path/to/test.ts

**Depends on:** #[issue-number] (if any)
**Blocks:** #[issue-number] (if any)

**Acceptance Criteria:**
- [ ] Criterion 1
- [ ] Criterion 2

**Reference:** See spec for detailed implementation notes.

Assign to milestone and add labels:

  • type: feature / type: bug / type: docs / etc.
  • area: core / area: plugins / area: testing / etc.
  • priority: high / priority: low (if needed)
  • good first issue (if appropriate)

No EPIC issue needed - tasks.md serves as the tracking document.

4. Implementation

For each task:

  1. Review the spec - Read relevant sections in spec.md, plan.md, tasks.md
  2. Check dependencies - Ensure dependent tasks are complete
  3. Create branch - git checkout -b feature/task-name
  4. Implement - Follow patterns in plan.md
  5. Test - Write tests per acceptance criteria
  6. Self-review - Check against acceptance criteria

5. Review & Merge

Create Pull Request:

  • Reference issue: "Closes #[issue-number]"
  • Reference spec: "Implements specs/phase-X/tasks.md#task-N"
  • Describe what was done
  • Note any deviations from spec
  • Run checks: pnpm lint, pnpm test, pnpm typecheck

Review checklist:

  • Matches acceptance criteria
  • Tests pass and coverage meets requirements
  • Follows patterns in spec
  • TypeScript strict mode passes
  • Linting passes
  • Documentation updated (if needed)

Phase Completion

When finishing a phase, follow this checklist (inspired by Spec-Kit):

1. Validate Definition of Done

Review the "Definition of Done" section in your phase's plan.md:

  • All implementation tasks complete
  • All tests passing (unit + integration)
  • Test coverage meets target (>80%)
  • Type checking passes (strict mode)
  • Linting passes
  • Example/demo works end-to-end
  • Documentation updated (JSDoc, README, etc.)

2. Runtime Validation

Test the implementation in real-world conditions:

  • Run example SDK/application
  • Test in target environments (browser, Node.js, etc.)
  • Check for runtime errors (console logs, network tab)
  • Validate performance metrics
  • Test edge cases and error handling

3. Repository Housekeeping

Clean up and finalize the phase:

  • All PRs reviewed and merged to main
  • Close phase milestone on GitHub
  • Update ROADMAP.md to mark phase complete
  • Tag release (if applicable): git tag v0.1.0
  • Update main README.md if needed

4. Retrospective (Optional but Recommended)

Create a completion summary in the spec directory (e.g., specs/phase-X/retrospective.md):

What to include:

  • Delivered: What was built
  • Metrics: Tests count, coverage %, lines of code
  • Lessons Learned: What worked well, what didn't
  • Deviations: Changes from original plan and why
  • Recommendations: Suggestions for next phase

Example structure:

# Phase X Retrospective

## Summary
Brief overview of what was accomplished.

## Metrics
- Tests: 192 passing
- Coverage: 98.97%
- Files: 15 created/modified
- LOC: ~2000

## What Went Well
- Event-based lifecycle simplified implementation
- High test coverage from the start

## What Could Improve
- Initial type definitions needed refinement

## Deviations from Plan
- Skipped separate Lifecycle class (used events instead)

## Recommendations for Next Phase
- Continue test-first approach
- Document patterns as we discover them

5. Prepare Next Phase

Set up for the next phase of work:

  • Review ROADMAP.md for next phase goals
  • Create new spec directory: specs/phase-X-name/
  • Write spec.md (what & why)
  • Write plan.md (how)
  • Write tasks.md (ordered breakdown)
  • Create GitHub milestone for next phase
  • Create issues from tasks.md

Why This Workflow?

✅ Benefits

Specs in Repository:

  • Version controlled with code
  • Reviewed in pull requests
  • Single source of truth
  • Can reference in commits/PRs
  • Searchable with code search

Issues for Tracking:

  • Assignable to people
  • Discussion threads
  • Link to PRs automatically
  • Progress tracking via milestones
  • Notifications

No Duplication:

  • Specs contain details
  • Issues link to specs
  • No need to sync two sources

🎯 Inspired By

This workflow combines patterns from:

  • Spec-Kit - Specs in repository
  • GitHub best practices - Issues for tracking
  • Production SDK patterns - Proven architectural approaches

File Structure

sdk-kit/
├── specs/                    # Feature specifications
│   ├── phase-1-core-sdk/
│   │   ├── spec.md          # Vision & goals
│   │   ├── plan.md          # Implementation details
│   │   ├── tasks.md         # Task breakdown (THE tracking doc)
│   │   └── contracts/       # Type definitions
│   └── phase-2-plugins/     # Future specs
│
├── packages/                 # Source code
│   ├── core/
│   ├── plugins/
│   └── testing/
│
├── notes/                    # Internal notes (gitignored)
│   └── issue2-patterns.md   # Private research
│
├── WORKFLOW.md              # This file
├── CONTRIBUTING.md          # Code contribution guide
├── ROADMAP.md               # High-level roadmap
└── README.md                # Project overview

Quick Reference

Planning a New Feature

  1. Create specs/feature-name/ directory
  2. Write spec.md (what & why)
  3. Write plan.md (how)
  4. Write tasks.md (ordered breakdown)
  5. Create milestone on GitHub
  6. Create issues from tasks.md

Starting a Task

  1. Read spec: specs/*/tasks.md#task-N
  2. Check dependencies are complete
  3. Create branch: feature/task-name
  4. Implement per plan.md patterns
  5. Write tests
  6. Create PR referencing issue & spec

Tracking Progress

  • Milestone view: See overall phase progress
  • Issues list: Filter by label/milestone
  • tasks.md: See dependencies and order

Examples

Example 1: Creating a Spec

# Create spec directory
mkdir -p specs/phase-2-plugins

# Create spec files
touch specs/phase-2-plugins/{spec,plan,tasks}.md
mkdir specs/phase-2-plugins/contracts

# Write specification
# (See specs/phase-1-core-sdk/ for template)

Example 2: Creating Issues from tasks.md

For each task in tasks.md:

# Create issue
gh issue create \
  --title "Implement Storage Plugin" \
  --body "📋 Spec: specs/phase-2-plugins/tasks.md#task-1
  
  Implement localStorage/sessionStorage plugin.
  
  Files:
  - packages/plugins/src/storage/index.ts
  - packages/plugins/src/storage/storage.test.ts
  
  Acceptance:
  - [ ] get/set/remove methods work
  - [ ] Test coverage > 90%
  " \
  --milestone "Phase 2: Plugins" \
  --label "type: feature" \
  --label "area: plugins"

Example 3: Implementing a Task

# 1. Read the spec
cat specs/phase-1-core-sdk/tasks.md | grep -A 20 "Task #1"

# 2. Create branch
git checkout -b feature/implement-types

# 3. Implement
# (Create files per plan.md)

# 4. Test
pnpm test

# 5. Create PR
gh pr create \
  --title "Implement TypeScript Types" \
  --body "Closes #1

Implements specs/phase-1-core-sdk/tasks.md#task-1

Created all type definitions for plugin system.
" \
  --assignee @me

Tips

For Maintainers

  • Keep specs up to date - Update in PRs when plans change
  • Reference specs in PRs - Makes reviews easier
  • Use parallel markers [P] - Helps distribute work
  • Update ROADMAP.md - Keep high-level view current

For Contributors

  • Read the spec first - Understand the "why" before coding
  • Follow patterns in plan.md - Consistency matters
  • Check dependencies - Don't start task #5 if #2 isn't done
  • Ask questions in issues - Better to ask than guess

For Everyone

  • Specs are living documents - Update them as we learn
  • Issues are for discussion - Use them for questions/feedback
  • PRs reference specs - Makes reviews context-aware
  • Milestones show progress - Celebrate completed phases!

Questions?

  • Process questions: Open a discussion or issue
  • Spec unclear: Comment on the issue or open a PR to clarify
  • Need help: Tag maintainers in the issue

See also: