Vela Labs Internal Wiki

Appearance

Process Evolution ​

How the GSD workflow evolved across 8 milestones of VelaPay development.

Overview ​

The GSD (Get Stuff Done) workflow has been the backbone of VelaPay development from v1.0 through v1.8. This document traces how the process has evolved — what was added, what was abandoned, and what became permanent.

The core cycle remains: milestone → phases → plans → execute → verify. But the supporting structures around this cycle have matured significantly.

v1.0–v1.1: Establishing the Base (5–8 phases, 20–26 plans) ​

How It Worked ​

The initial workflow was minimal:

1. Define milestone in ROADMAP.md
2. Break into phases
3. For each phase: discuss → plan → execute → verify
4. Move to next phase

There was no workstream structure, no explicit validation phases, and no milestone audit. Phase directories were flat under .planning/.

What Worked ​

  • The basic phase → plan → execute cycle proved sound
  • SUMMARY.md files provided basic state recovery between sessions
  • Wave-based execution (plans grouped by dependency) emerged organically

What Didn't Work ​

  • No workstream structure meant all phases were sequential, even when they could have been parallel
  • No validation phases meant test debt accumulated silently
  • No milestone audit meant issues were only discovered during the next milestone's prerequisite checks
  • Phase numbering was linear (1, 2, 3...) with no way to insert urgent work

Carried Forward ​

  • The basic phase → plan → execute cycle
  • SUMMARY.md for state recovery
  • Wave-based plan grouping

Abandoned ​

  • Flat phase directory structure (replaced by workstreams in v1.2)
  • Linear phase numbering (replaced by decimal insertion in v1.7)

v1.2: Workstreams + Validation + Gap Closure (10 phases, 36 plans) ​

How It Changed ​

v1.2 was the first milestone that outgrew the simple linear workflow. With 10 phases, it needed structure:

.planning/
  milestones/
    v1.2/
      workstream-admin/      # Phases 1-4
      workstream-billing/    # Phases 5-10
      Phase-20/              # Validation/gap-closure
      Phase-21/
      Phase-22/
      Phase-23/

Key additions:

  1. Workstream directories — grouped related phases by domain
  2. Wave-0 test stubs — written upfront at the start of each wave
  3. Explicit validation phases (20-23) — dedicated to closing deferred test debt
  4. Service binding pattern — admin RPC isolated behind Cloudflare service binding

The Gap-Closure Discovery ​

Phases 20-23 were the first dedicated gap-closure phases. They addressed test stubs that had been deferred during feature development. The discovery: closing gaps in a dedicated phase is more effective than trying to close them in-band because:

  • The audit provides a complete inventory of gaps
  • Dedicated phases can focus exclusively on validation without feature distractions
  • Gap-closure phases have different acceptance criteria than feature phases

What Worked ​

  • Workstream structure kept related phases together
  • Validation phases caught real issues (keeper loop error handling, event emission gaps)
  • Service binding pattern prevented admin route exposure

What Didn't Work ​

  • Phases 20-22 were created outside the workstream directory, causing fragmentation
  • The validation phases were added reactively rather than planned upfront

Carried Forward ​

  • Workstream directory structure
  • Gap-closure phase pattern
  • Service binding for admin isolation
  • Wave-0 test stubs

v1.3: Milestone Audit Discipline (3 phases, 13 plans) ​

How It Changed ​

v1.3 was a focused milestone (auth migration + Better Auth) but introduced the most important process change: milestone audit before archival.

1. Execute feature phases
2. Run gsd-audit-milestone (mid-milestone, ~60% completion)
3. Execute remaining phases
4. Run gsd-audit-milestone (pre-archival)
5. Archive only after audit passes

Key additions:

  1. Mid-milestone audit — catches issues while context is fresh
  2. Pre-archival audit — catches anything missed before milestone closes
  3. Centralized auth redirect handling — Better Auth plugin for redirect management
  4. Playwright E2E for auth flows — automated testing of login/signup/logout

The Audit Discipline Discovery ​

The v1.3 audit found cross-plan integration testing gaps that were invisible during individual phase execution. Specifically:

  • Auth middleware wasn't applied to newly created webhook endpoints
  • Session migration had edge cases when wallet-only users encountered email-required routes
  • Better Auth plugin configuration was incomplete for the organization-based merchant model

What Worked ​

  • Milestone audit caught real integration bugs
  • Better Auth plugin ecosystem reduced custom auth code
  • Playwright E2E tests now guard auth regression

What Didn't Work ​

  • Auth was still partially mixed with feature work, causing integration churn
  • Security middleware was applied in a separate phase rather than co-located with features

Carried Forward ​

  • Milestone audit discipline (mid-milestone + pre-archival)
  • Centralized auth redirect pattern
  • Better Auth plugin adoption

v1.4: CU Profiling Gate (2 phases, 13 plans) ​

How It Changed ​

v1.4 was small (agent mandate protocol) but introduced a technical gate:

  • CU profiling gate — agent mandates required compute unit profiling before approval
  • This ensured that agent spending mandates wouldn't create pathological on-chain compute patterns

What Worked ​

  • CU profiling caught an edge case where recursive agent calls could exceed the compute budget
  • Small milestone scope meant focused execution

What Didn't Work ​

  • Only 2 phases, so limited process evolution
  • No validation phase (scope was too small to justify one)

Carried Forward ​

  • CU profiling as a gate for new instruction types

v1.5: Shared Patterns + Tech Debt Acceptance (7 phases, 37 plans) ​

How It Changed ​

v1.5 introduced two significant process changes:

  1. Shared checkout-session pattern — vela-checkout and vela-portal both use the same session creation flow
  2. Explicit tech debt tracking — rather than leaving deferred items implicit, they're tracked in REQUIREMENTS.md with explicit "deferred to v1.x" annotations

Key structural changes:

  • Public billing surfaces (vela-checkout, vela-portal) recognized as separate repos
  • Proxy pattern for public→internal routing
  • Checkout sessions as the shared abstraction between checkout and portal

The Tech Debt Acceptance Discovery ​

Previous milestones treated deferred items as failures. v1.5 recognized that some deferral is strategic:

  • The webhook SDK was deferred from v1.5 to v1.7+ because the event schema wasn't stable
  • Multi-token billing was deferred from v1.5 to v1.7 because USDC-only was sufficient for launch
  • The key insight: explicitly track what's deferred and why, rather than leaving it implicit

What Worked ​

  • Shared checkout-session pattern reduced code duplication
  • Explicit tech debt tracking provided clarity on what was intentionally deferred
  • High velocity (18.5 plans/day) — highest of any milestone

What Didn't Work ​

  • Some deferred items didn't get clear enough "why" annotations
  • The proxy pattern added latency to public-facing routes

Carried Forward ​

  • Shared checkout-session pattern
  • Explicit tech debt tracking in REQUIREMENTS.md
  • Strategic deferral with clear documentation

v1.6: Docs-Only Milestone Adaptation (4 phases, 16 plans) ​

How It Changed ​

v1.6 was the first docs-only milestone. It required adapting the GSD workflow for non-code work:

  1. Phase consolidation — originally 5 phases, consolidated to 3 content phases + 1 gap closure
  2. Build-time link validation — starlight-links-validator as quality gate
  3. Audience-based IA — starlight-sidebar-topics for multi-audience navigation
  4. Milestone audit for non-code work — demonstrated that audit discipline applies beyond code

The Phase Consolidation Discovery ​

Docs phases have lower coupling than code phases. Multiple docs chapters can be written in parallel because they don't share runtime dependencies. This means:

  • Docs phases can be merged more aggressively than code phases
  • The risk of consolidation is lower (broken links caught by validator)
  • Content phases benefit from batched writing (consistent voice, cross-referencing)

What Worked ​

  • Phase consolidation (5→4) saved a session without losing coverage
  • Build-time link validation caught 34 broken links
  • Audience-based IA (developers, merchants, protocol) improved navigation
  • Milestone audit caught docs-specific issues (missing migration guides, stale API references)

What Didn't Work ​

  • Docs milestones have different estimation characteristics — plans take longer to review than to write
  • rehype-mermaid SSR diagrams required custom configuration that took a full plan to set up

Carried Forward ​

  • Phase consolidation for docs work
  • Build-time link validation
  • Audience-based IA
  • Milestone audit for non-code work

v1.7: Protocol Refactoring + Gap-Closure Pattern (5 phases, 29 plans) ​

How It Changed ​

v1.7 was the most technically complex milestone, involving a full protocol/SDK refactor:

  1. Versioned accounts — every account gets version: u8 + _reserved: [u8; 64]
  2. Gap-closure phase pattern formalized — dedicated phases for closing validation gaps
  3. "Unit tests pass ≠ integration works" lesson — Phase 42 passed unit tests but had integration gaps
  4. IDL freshness as deployment concern — SDK IDL must match deployed program
  5. Two gap-closure phases — integration drift (Phase 43) + traceability drift (Phase 44)

The Double Gap-Closure Discovery ​

Phase 42 skipped the verifier because unit tests passed. This created two distinct categories of gaps:

  1. Integration drift — individual components worked in isolation but not together
  2. Traceability drift — SUMMARY.md files and requirements tracking fell behind actual implementation

These required separate gap-closure phases because:

  • Integration gaps require code changes and new tests
  • Traceability gaps require documentation and state file updates
  • Attempting both in one phase would mix code and docs concerns

The Account Versioning Discovery ​

Adding _reserved: [u8; 64] to every account costs ~64 bytes per account but provides:

  • Additive field migrations without account closure cycles
  • Streaming payments added without breaking existing mandates
  • Future multi-token support without redeployment
  • Cost: negligible. Benefit: significant.

What Worked ​

  • Versioned accounts enabled clean streaming addition in v1.8
  • Centralized PDAFactory eliminated seed derivation bugs
  • Dynamic program ID resolution removed hardcoded config

What Didn't Work ​

  • Skipping verifier on Phase 42 created 30% overhead (two gap-closure phases)
  • IDL freshness wasn't checked automatically — led to SDK/program mismatch

Carried Forward ​

  • Versioned accounts for all new account types
  • Gap-closure phase as formal pattern
  • Dynamic program ID resolution
  • Centralized PDAFactory

v1.8: Aggressive Phase Merging (3 phases, 47 plans) ​

How It Changed ​

v1.8 consolidated from a planned 5 phases to 3 phases:

Phase 45: Streaming + SDK builders
Phase 46: Dashboard UI + billing surfaces
Phase 47: Webhook events + staging validation

The merging rationale:

  • Phase 45+46 share SDK builders — streaming SDK methods are used by both dashboard and public surfaces
  • Phase 46+47 share dashboard UI — webhook configuration is a dashboard feature
  • Phase 47 must be last — webhook event types depend on streaming (45) and dashboard (46) events

The Sequencing Discovery ​

Phase merging works when phases share implementation artifacts. The key insight:

  • Streaming is net-new primitive (no dependencies on existing features)
  • Dashboard UI consumes streaming SDK (depends on Phase 45)
  • Webhooks tag events from both streaming and dashboard (depends on 45+46)

This creates a clean dependency chain: 45 → 46 → 47. Merging is safe because the dependency direction is unambiguous.

What Worked (So Far) ​

  • Phase merging increased velocity (47 plans across 3 phases)
  • Clear dependency chain prevented sequencing conflicts
  • Streaming as a net-new primitive had no coupling with existing features

What Didn't Work (So Far) ​

  • Higher plans-per-phase ratio means longer individual sessions
  • More plans means more context to maintain across the session

Process Maturity Summary ​

What Became Permanent ​

ProcessOriginWhy It Stuck
Phase → Plan → Execute cyclev1.0Fundamental workflow unit
Workstream directory structurev1.2Scales to multi-domain milestones
Gap-closure phasesv1.2Prevents validation debt accumulation
Milestone audit (mid + pre-archival)v1.3Catches real bugs at both checkpoints
Explicit tech debt trackingv1.5Provides clarity on strategic deferrals
Build-time link validationv1.6Zero-cost quality gate for docs
Versioned accountsv1.7Cheap insurance for protocol evolution
Phase merging for shared artifactsv1.8Increases velocity when dependencies are clear

What Was Abandoned ​

ProcessOriginWhy Abandoned
Flat phase directoriesv1.0Doesn't scale past 5 phases
Linear phase numberingv1.0Can't insert urgent work
In-band validation closurev1.0-v1.1Less effective than dedicated phases
Implicit tech debt trackingv1.0-v1.4Creates confusion about what's deferred
Mixed auth + feature phasesv1.0-v1.2Integration complexity exceeds cost of separate phase

Process Selection Guide ​

Milestone TypeRecommended Process
Feature-heavy (5+ phases)Workstreams + gap-closure phases + mid-milestone audit
Focused (2-4 phases)Linear phases + pre-archival audit
Docs-onlyAggressive consolidation + build-time validation + pre-archival audit
Protocol refactorVersioned accounts + PDAFactory + dedicated integration testing
Auth migrationSeparate auth phase + E2E tests + migration verification

Internal knowledge base for the Vela Labs workspace.

Grounded in .planning/, root research docs, repo manifests, and milestone artifacts.