/spark

Spark Technical Integration Patterns Reference

Purpose: define how Spark hands proposals to Sherpa or Builder and how technical constraints should appear in the proposal.

Contents

• Direct Builder handoff
• DDD guidance
• API integration requirements
• Sherpa feedback loop
• Scope adjustment rules
• Handoff checklists

Direct Builder Handoff

## SPARK_TO_BUILDER_HANDOFF

Use direct Builder handoff when:

• the feature is simple and independent
• the risk is low and the requirements are clear
• an existing implementation pattern already exists
• the estimate is hours-level

Prefer Sherpa when:

• the work is multi-step
• dependencies or uncertainty are material
• the estimate is 1 day or more

Direct handoff packet

Required fields:

• Feature
• Proposal Doc
• Bypass Sherpa
• Technical Specification
  • Core Requirement
  • User Story
  • Domain Model Requirements

Checklist before direct Builder handoff:

• feature is simple (< 4 hours estimate)
• existing patterns can be followed
• no external dependency is unresolved
• risk is low
• technical requirements are explicit

DDD Guidance

## DDD Pattern Recommendation

Choose the lightest appropriate pattern:

Entity template

### Entity: [EntityName]
- Identity
- Properties
- State Transitions
- Invariants
- Methods Expected

Value Object template

### Value Object: [VOName]
- Purpose
- Properties
- Creation Validation
- Equality
- Use Cases

Keep the expected signature when relevant:

static create(raw: RawInput): Result<[VOName], ValidationError>

Aggregate Root template

### Aggregate Root: [AggregateName]
- Root Entity
- Child Entities
- Aggregate Invariants
- Transaction Boundary

API Integration Requirements

## API Integration Requirements

Required fields:

• External API
• Purpose
• Connection Requirements
• Retry Strategy
• Rate Limiting
• Error Handling
• Data Validation
• Fallback Strategy

Keep these default retry rules unless the target API requires something stricter:

Backoff defaults:

initial_delay: 1s
max_delay: 30s
multiplier: 2
jitter: 0.1

Circuit-breaker defaults:

failure_threshold: 5
reset_timeout: 60s
half_open_requests: 3

Sherpa Feedback Loop

## SHERPA_TO_SPARK_FEEDBACK

Use when breakdown exposes feasibility, scope, dependency, risk, or resource concerns.

Required fields:

• Feature
• Proposal Doc
• Feedback Type
• Breakdown Attempt Summary
  • Total Steps Identified
  • Estimated Total Time
  • High Risk Steps (0-1 acceptable)
• Feasibility Concerns

## SPARK_ITERATION_ON_SHERPA_FEEDBACK

Required fields:

• Original Proposal
• Sherpa Feedback
• Iteration
• Accepted Adjustments
• Revised Scope

Scope Adjustment

## SCOPE_ADJUSTMENT

Required fields:

• Original Feature
• Adjustment Reason
• Impact Analysis
• Adjustment Options

Preferred adjustments:

Integration Workflow

Flow:

• Spark drafts the proposal
• send to Sherpa if complexity or uncertainty is material
• send directly to Builder only for simple, low-risk work
• if Sherpa pushes back, iterate the proposal before build

Handoff Checklists

Before Sherpa handoff:

• user story is clear
• acceptance criteria are testable
• DDD hints are suggested, not over-specified
• API requirements are listed when relevant
• priority is explicit

After Sherpa feedback:

• review every concern
• choose the adjustment path
• update the proposal document
• communicate scope changes
• resubmit if needed