Code-Centric Goal-Oriented Action Planning

SPARC-integrated planning for software development objectives with measurable outcomes

Quick Start

# Define code goal
Goal: Implement OAuth2 authentication

# SPARC-GOAP generates phased plan:
Phase 1 (Specification): Define requirements, acceptance criteria
Phase 2 (Pseudocode): Design algorithms, state machines
Phase 3 (Architecture): Design components, API contracts
Phase 4 (Refinement): TDD implementation cycles
Phase 5 (Completion): Integration, validation, deployment

# Execute with SPARC commands
npx claude-flow sparc tdd "OAuth2 authentication"

When to Use

• Feature implementation requiring systematic breakdown
• Performance optimization with measurable targets
• Testing strategy development with coverage goals
• API development with clear contract definitions
• Database evolution with migration planning
• Technical debt reduction with incremental milestones

Prerequisites

• Understanding of SPARC methodology phases
• Clear definition of desired outcome
• Access to codebase for state analysis
• Measurable success criteria

Core Concepts

SPARC Phases in Goal Planning

Phase	GOAP Role	Deliverables
Specification	Define goal state	Requirements, acceptance criteria
Pseudocode	Plan actions	Algorithms, state transitions
Architecture	Structure solution	Components, interfaces
Refinement	Iterate with TDD	Tests, implementation
Completion	Validate goal	Deployment, metrics

Code State Analysis

current_state = {
  test_coverage: 45,
  performance_score: 'C',
  tech_debt_hours: 120,
  features_complete: ['auth', 'user-mgmt'],
  bugs_open: 23
}

goal_state = {
  test_coverage: 80,
  performance_score: 'A',
  tech_debt_hours: 40,
  features_complete: [...current, 'payments', 'notifications'],
  bugs_open: 5
}

Milestone Definition

interface CodeMilestone {
  id: string;
  description: string;
  sparc_phase: 'specification' | 'pseudocode' | 'architecture' | 'refinement' | 'completion';
  preconditions: string[];
  deliverables: string[];
  success_criteria: Metric[];
  estimated_hours: number;
  dependencies: string[];
}

Implementation Pattern

class SPARCGoalPlanner {
  async achieveGoal(goal: CodeGoal): Promise<GoalResult> {
    // 1. SPECIFICATION: Define goal state
    const spec = await this.specifyGoal(goal);

    // 2. PSEUDOCODE: Plan action sequence
    const actionPlan = await this.planActions(spec);

    // 3. ARCHITECTURE: Structure solution
    const architecture = await this.designArchitecture(actionPlan);

    // 4. REFINEMENT: Iterate with TDD
    const implementation = await this.refineWithTDD(architecture);

    // 5. COMPLETION: Validate and deploy
    return await this.completeGoal(implementation, spec);
  }

  async findOptimalPath(
    currentState: CodeState,
    goalState: CodeState
  ): Promise<ActionPlan> {
    const actions = this.getAvailableSPARCActions();
    return this.aStarSearch(currentState, goalState, actions);
  }
}

Configuration

sparc_goap_config:
  phases:
    specification:
      command: "npx claude-flow sparc run spec-pseudocode"
      timeout_minutes: 30

    architecture:
      command: "npx claude-flow sparc run architect"
      timeout_minutes: 45

    refinement:
      command: "npx claude-flow sparc tdd"
      timeout_minutes: 120

    completion:
      command: "npx claude-flow sparc run integration"
      timeout_minutes: 60

  metrics:
    test_coverage_target: 80
    performance_target: "A"
    max_tech_debt_hours: 40

  risk_assessment:
    technical_weight: 0.3
    timeline_weight: 0.3
    quality_weight: 0.2
    security_weight: 0.2

Usage Examples

Example 1: Feature Implementation Plan

goal: implement_payment_processing_with_sparc

sparc_phases:
  specification:
    command: "npx claude-flow sparc run spec-pseudocode 'payment processing'"
    deliverables:
      - requirements_doc
      - acceptance_criteria
      - test_scenarios
    success_criteria:
      - all_payment_types_defined
      - security_requirements_clear
      - compliance_standards_identified

  pseudocode:
    command: "npx claude-flow sparc run pseudocode 'payment flow algorithms'"
    deliverables:
      - payment_flow_logic
      - error_handling_patterns
      - state_machine_design

  architecture:
    command: "npx claude-flow sparc run architect 'payment system design'"
    deliverables:
      - system_components
      - api_contracts
      - database_schema

  refinement:
    command: "npx claude-flow sparc tdd 'payment feature'"
    deliverables:
      - unit_tests
      - integration_tests
      - implemented_features
    success_criteria:
      - test_coverage_80_percent
      - all_tests_passing

  completion:
    command: "npx claude-flow sparc run integration 'deploy payment system'"
    deliverables:
      - deployed_system
      - documentation
      - monitoring_setup

goap_milestones:
  - setup_payment_provider:
      sparc_phase: specification
      preconditions: [api_keys_configured]
      deliverables: [provider_client, test_environment]
      success_criteria: [can_create_test_charge]

  - implement_checkout_flow:
      sparc_phase: refinement
      preconditions: [payment_provider_ready, ui_framework_setup]
      deliverables: [checkout_component, payment_form]
      success_criteria: [form_validation_works, ui_responsive]

  - add_webhook_handling:
      sparc_phase: completion
      preconditions: [server_endpoints_available]
      deliverables: [webhook_endpoint, event_processor]
      success_criteria: [handles_all_event_types, idempotent_processing]

Example 2: Performance Optimization Goal

goal: reduce_api_latency_50_percent

analysis:
  - profile_current_performance:
      tools: [profiler, APM, database_explain]
      metrics: [p50_latency, p99_latency, throughput]

optimizations:
  - database_query_optimization:
      sparc_phase: refinement
      actions: [add_indexes, optimize_joins, implement_pagination]
      expected_improvement: 30%
      success_metric: "p99 < 100ms"

  - implement_caching_layer:
      sparc_phase: architecture
      actions: [redis_setup, cache_warming, invalidation_strategy]
      expected_improvement: 25%

  - code_optimization:
      sparc_phase: refinement
      actions: [algorithm_improvements, parallel_processing, batch_operations]
      expected_improvement: 15%

Example 3: Testing Strategy Goal

goal: achieve_80_percent_coverage
current_coverage: 45

test_pyramid:
  unit_tests:
    target: 60%
    sparc_phase: refinement
    focus: [business_logic, utilities, validators]

  integration_tests:
    target: 25%
    sparc_phase: completion
    focus: [api_endpoints, database_operations, external_services]

  e2e_tests:
    target: 15%
    sparc_phase: completion
    focus: [critical_user_journeys, payment_flow, authentication]

milestones:
  - milestone_55:
      actions: [add_unit_tests_for_core_services]
      deadline: "week 1"

  - milestone_65:
      actions: [add_integration_tests_for_api]
      deadline: "week 2"

  - milestone_80:
      actions: [add_e2e_tests, increase_unit_coverage]
      deadline: "week 3"

Execution Checklist

• Analyze current code state (coverage, performance, debt)
• Define goal state with measurable criteria
• Map goal to SPARC phases
• Generate GOAP milestones for each phase
• Estimate effort and dependencies
• Execute SPARC commands for each phase
• Track metrics throughout execution
• Validate goal achievement with success criteria
• Document patterns for future goals

Best Practices

• Measurable Goals: Every goal needs quantifiable success criteria
• Phase Alignment: Map GOAP actions to appropriate SPARC phases
• TDD Integration: Use refinement phase for test-first development
• Incremental Progress: Track metrics at each milestone
• Risk Assessment: Evaluate technical, timeline, quality, security risks
• Pattern Learning: Store successful plans for reuse

Error Handling

Goal Infeasibility

// Goal cannot be achieved with available resources
if (!canAchieveGoal(currentState, goalState, constraints)) {
  // Suggest achievable subset
  const achievableGoal = findMaximalAchievableSubset(goalState);
  console.log(`Full goal not achievable. Suggested: ${achievableGoal}`);

  // Identify blocking constraints
  const blockers = identifyBlockers(goalState);
  console.log(`Blocked by: ${blockers}`);
}

Phase Failures

// SPARC phase did not complete successfully
if (phaseResult.failed) {
  // Identify specific failures
  const failures = phaseResult.failedCriteria;

  // Attempt retry with adjusted parameters
  if (canRetry(failures)) {
    await retryPhase(phase, adjustedConfig);
  } else {
    // Replan from current state
    await replanFromPhase(phase);
  }
}

Metrics & Success Criteria

Code Quality Metrics

Metric	Target	Measurement
Cyclomatic Complexity	< 10	Per function
Code Duplication	< 3%	Codebase-wide
Test Coverage	> 80%	Line coverage
Technical Debt Ratio	< 5%	SonarQube

Performance Metrics

Metric	Target	Measurement
Response Time (p99)	< 200ms	APM
Throughput	> 1000 req/s	Load test
Error Rate	< 0.1%	Monitoring
Availability	> 99.9%	Uptime

Delivery Metrics

Metric	Target	Measurement
Lead Time	< 1 day	Deploy tracking
Deploy Frequency	> 1/day	CI/CD
MTTR	< 1 hour	Incident tracking
Change Failure Rate	< 5%	Rollback rate

Integration Points

MCP Tools

// Initialize SPARC-enhanced swarm
mcp__claude-flow__swarm_init({
  topology: "hierarchical",
  maxAgents: 5
});

// Spawn SPARC-specific agents
mcp__claude-flow__agent_spawn({
  type: "sparc-coder",
  capabilities: ["specification", "pseudocode", "architecture", "refinement", "completion"]
});

// Orchestrate development tasks
mcp__claude-flow__task_orchestrate({
  task: "implement_oauth_system",
  strategy: "adaptive",
  priority: "high"
});

// Store successful patterns
mcp__claude-flow__memory_usage({
  action: "store",
  namespace: "code-patterns",
  key: "oauth_implementation_plan",
  value: JSON.stringify(successfulPlan)
});

SPARC Commands

# Full SPARC-GOAP workflow
npx claude-flow sparc run spec-pseudocode "user authentication feature"
npx claude-flow sparc run architect "authentication system design"
npx claude-flow sparc tdd "authentication feature" --track-goals
npx claude-flow sparc run integration "deploy authentication" --validate-goals
npx claude-flow sparc verify "authentication feature complete"

# Batch processing
npx claude-flow sparc batch spec,arch,refine "user management system"
npx claude-flow sparc concurrent tdd tasks.json

Related Skills

• planning-goal - General GOAP planning
• sparc-workflow - SPARC methodology
• testing-tdd-london - TDD implementation

References

• SPARC Methodology
• GOAP in Game AI
• TDD Best Practices

Version History

• 1.0.0 (2026-01-02): Initial release - converted from code-goal-planner agent