groundswell 0.0.2 → 1.0.0

package/plan/001_d3bb02af4886/docs/research/P1P2/RESEARCH_SUMMARY.md

@@ -1,342 +0,0 @@
-# AI Reflection and Self-Correction Research - Summary
-
-## Research Completion Report
-
-**Project**: Best practices for implementing AI reflection/self-correction patterns in agent orchestration systems
-
-**Completion Date**: December 8, 2025
-
-**Total Research Content**: 24,500+ words across 8 comprehensive documents
-
----
-
-## Deliverables
-
-### Core Documents Created
-
-1. **REFLECTION_RESEARCH_REPORT.md** (45 KB, 9,500+ words)
-   - Comprehensive foundational research
-   - 11 major sections covering theory, implementation, and best practices
-   - Topics: reflection patterns, prompt templates, introspection tools, security, common pitfalls
-   - Research references and citations from 2024-2025
-
-2. **reflection-implementation-guide.md** (37 KB, 5,200+ words)
-   - Production-ready code examples
-   - 7 implementation patterns in Python and TypeScript
-   - Loop detection systems
-   - Token budget management
-   - Security validation frameworks
-   - Hierarchical reflection systems
-   - Integration examples
-
-3. **reflection-quick-reference.md** (14 KB, 2,100+ words)
-   - Decision trees for when to use reflection
-   - Approach selection matrices
-   - 4 configuration profiles (Speed, Quality, Balanced, Safety-Critical)
-   - Prompt templates with complexity levels
-   - Performance benchmarks
-   - Troubleshooting guides
-   - Security checklists
-
-4. **REFLECTION_INDEX.md** (9.1 KB, 1,200+ words)
-   - Navigation guide for the research package
-   - Quick-start guides by use case
-   - Key research findings summary
-   - FAQ section
-   - 5-minute getting started guide
-
-### Additional Research Documents (Pre-existing)
-
-5. **reflection-patterns.md** - Detailed pattern analysis
-6. **reflection-decision-matrix.md** - Advanced decision frameworks
-7. **reflection-integration-guide.md** - Framework-specific integration
-8. **reflection-code-patterns.md** - Additional code patterns
-
----
-
-## Research Coverage
-
-### 1. Reflection Patterns for LLM Agents
-
-Covered 6 major approaches:
-- Automatic retry with self-correction
-- Multi-level reflection (prompt, agent, workflow, system levels)
-- Error analysis and context injection
-- Reflexion framework (evidence-grounded)
-- Language Agent Tree Search (LATS) with Monte Carlo search
-- Spontaneous Self-Correction (SPOC) - 2025 research
-
-### 2. Implementation Patterns
-
-Documented patterns:
-- Reflection prompt templates (5 main templates, task-specific variations)
-- Maximum retry limits and exponential backoff strategies
-- State preservation during reflection cycles
-- Token budget allocation and management
-- Loop detection mechanisms (4 strategies)
-- Context window management and compression
-
-### 3. Introspection Tools for Agents
-
-Defined 6 core introspection tools:
-- `get_agent_metadata` - Agent capabilities and status
-- `read_parent_context` - Parent goals and constraints
-- `read_sibling_context` - Sibling agents' work
-- `read_execution_history` - Own prior attempts
-- `read_workflow_state` - Overall progress
-- `check_resource_constraints` - Token/time remaining
-
-Security model for introspection:
-- Role-based access control (RBAC)
-- Credential masking and filtering
-- Execution isolation
-- Permission matrices
-
-### 4. Best Practices from Existing Frameworks
-
-Research integrated from:
-- **LangChain/LangGraph**: Reflection loops with state management
-- **CrewAI**: Hierarchical process with manager agent review
-- **Reflexion Paper**: Evidence-grounded feedback mechanisms
-- **AutoGPT**: Error analysis and feedback loops
-- **OpenAI/Anthropic**: Built-in reasoning and reflection
-
-### 5. Common Pitfalls and Prevention
-
-Documented 4 major pitfalls with solutions:
-1. **Infinite Loops**: Detection strategies and recovery mechanisms
-2. **Context Window Bloat**: Compression, summarization, external memory
-3. **Diminishing Returns**: Quality threshold and stopping conditions
-4. **Stale Context**: Timestamp validation and refresh strategies
-
----
-
-## Key Findings from Research
-
-### Finding 1: External Feedback is Critical
-- With external feedback: 80-95% effectiveness
-- Without external feedback: 30-50% effectiveness
-- Implication: Always implement feedback mechanisms before reflection
-
-### Finding 2: Minimal Signals Help
-- Simple "Try again" signals improve performance 60%+
-- Minimal "Wait" triggers reduce self-correction blind spots by 89.3%
-- Implication: Even basic reflection is worthwhile
-
-### Finding 3: 2-3 Cycles is Optimal
-- Diminishing returns after 3 cycles
-- Sweet spot: 2-3 reflection attempts
-- Additional cycles add cost with minimal benefit
-
-### Finding 4: Information Richness Matters
-- Best: Instructions + Explanation + Solution
-- Good: Evidence-grounded with citations
-- Acceptable: Advice/suggestions
-- Limited: Keywords or simple retry
-
-### Finding 5: Multi-Agent Reflection Outperforms Self-Reflection
-- Self-correction blind spot affects ~64.5% of non-reasoning models
-- Multi-agent (critic + generator) shows 90% effectiveness
-- Tool-interactive with validation shows 85% effectiveness
-
----
-
-## Security Considerations Documented
-
-### Attack Vectors Addressed
-1. Prompt injection via reflection feedback
-2. Credential exposure in execution history
-3. Unauthorized context access across agents
-4. Agent context leakage
-5. Denial of service via loop-based attacks
-
-### Defense Patterns
-1. Plan-Then-Execute pattern (action whitelist)
-2. Action-Selector pattern (hardcoded safe actions)
-3. Dual-Agent quarantine model (Privileged + Quarantined)
-4. Input sanitization and validation
-5. Role-based access control (RBAC)
-
----
-
-## Code Examples Provided
-
-### Python Examples
-- Reflexion pattern with evidence grounding (class-based)
-- Loop detection with similarity analysis
-- Context window management with budget allocation
-- Hierarchical reflection framework with multi-level support
-- Error analysis and context injection patterns
-
-### TypeScript Examples
-- Basic reflection loop with quality evaluation
-- Loop detection system with 4 detection strategies
-- Secure reflection executor with input validation
-- Metrics collection and performance tracking
-- Orchestration integration example
-
-All examples include:
-- Error handling
-- Type safety
-- Security validation
-- Production-ready structure
-- Integration hooks
-
----
-
-## Configuration Frameworks
-
-### Provided Profiles
-1. **Speed-Optimized**: max_attempts=1, minimal overhead
-2. **Quality-Optimized**: max_attempts=3, full reflection
-3. **Balanced** (Recommended): max_attempts=2, trade-off
-4. **Safety-Critical**: max_attempts=3, strict validation
-
-### Configuration Parameters
-- max_attempts: 1-3 (typically 2-3)
-- reflection_style: minimal, self_critique, evidence_grounded, multi_agent
-- token_budget: 20K-150K depending on task
-- timeout: 10s-120s depending on complexity
-- quality_threshold: 0.8 (80% good enough)
-
----
-
-## Quick Reference Materials
-
-Created for fast decision-making:
-1. Decision tree (1 page) - Determine if reflection is needed
-2. Approach selection matrix (by task type)
-3. Prompt templates (4 complexity levels)
-4. Performance benchmarks (code generation, analysis, writing)
-5. Token budget calculator (with examples)
-6. Stopping conditions checklist (6 conditions)
-7. Security checklist (10 items)
-8. Integration checklist (12 items)
-9. Troubleshooting guide (8 common issues)
-10. FAQ (7 key questions)
-
----
-
-## Sources and References
-
-Research synthesized from:
-- **Academic Papers** (2024-2025):
-  - Self-Reflection in LLM Agents (effectiveness study)
-  - When Can LLMs Actually Correct Their Own Mistakes (critical survey)
-  - Self-Correction Bench (blind spot analysis)
-  - Design Patterns for Securing LLM Agents (prompt injection defense)
-
-- **Framework Documentation**:
-  - LangGraph/LangChain reflection tutorials
-  - CrewAI hierarchical process documentation
-  - OpenAI API documentation
-  - Anthropic Claude documentation
-
-- **Industry Sources**:
-  - OWASP Gen AI Security Project
-  - 2025 LLM security guidelines
-  - DeepLearning.AI agentic patterns course
-  - IBM, Microsoft, Google DeepMind research
-
----
-
-## How to Use This Research
-
-### For Implementation
-1. Start with REFLECTION_INDEX.md (navigation guide)
-2. Use decision tree in reflection-quick-reference.md
-3. Select approach from matrix
-4. Copy code from reflection-implementation-guide.md
-5. Review security considerations in REFLECTION_RESEARCH_REPORT.md
-
-### For Learning
-1. Read Section 1 of REFLECTION_RESEARCH_REPORT.md (concepts)
-2. Study framework examples (Section 5)
-3. Review code patterns (reflection-implementation-guide.md)
-4. Understand pitfalls (Section 5 of main report)
-
-### For Maintenance
-1. Reference monitoring section (Section 9)
-2. Use metrics collection code (reflection-implementation-guide.md Section 6)
-3. Create dashboard based on essential metrics
-4. Monitor for issues using troubleshooting guide
-
----
-
-## Next Steps for Your Project
-
-Based on this research, recommend:
-
-1. **Architecture Design**
-   - Choose reflection approach based on use cases
-   - Plan introspection tool access model
-   - Design security boundaries
-
-2. **Implementation**
-   - Select configuration profile (Balanced recommended)
-   - Implement loop detection first
-   - Add token budgeting
-   - Integrate with LLM client
-
-3. **Testing**
-   - Unit test reflection patterns
-   - Load test token budgets
-   - Security test with adversarial inputs
-   - Measure quality improvements
-
-4. **Monitoring**
-   - Set up metrics collection
-   - Create performance dashboard
-   - Define alerting rules
-   - Track ROI of reflection
-
-5. **Documentation**
-   - Document reflection configuration per task
-   - Document introspection access policies
-   - Create runbooks for common issues
-   - Train teams on system usage
-
----
-
-## Research Quality Metrics
-
-- Total words: 24,500+
-- Number of code examples: 15+
-- Sections with prompts: 5 major sections
-- Security patterns documented: 5
-- Implementation patterns: 7
-- Configuration profiles: 4
-- Decision matrices: 2+
-- Quick reference guides: 10+
-- Code completeness: Production-ready
-
----
-
-## Document Access
-
-All research files are located at:
-**`./plan/P1P2/research/`**
-
-Files:
-- REFLECTION_RESEARCH_REPORT.md
-- reflection-implementation-guide.md
-- reflection-quick-reference.md
-- REFLECTION_INDEX.md
-- reflection-patterns.md
-- reflection-decision-matrix.md
-- reflection-integration-guide.md
-- reflection-code-patterns.md
-
----
-
-## Version and Date
-
-- **Package Version**: 1.0
-- **Created**: December 8, 2025
-- **Based on Research**: 2024-2025 papers and frameworks
-- **Status**: Complete and ready for implementation
-
----
-
-This comprehensive research package provides everything needed to understand and implement AI reflection and self-correction patterns in agent orchestration systems. The combination of theory, practical code, decision frameworks, and security guidance creates a complete resource for building reliable, efficient, and safe reflection systems.
-

package/plan/001_d3bb02af4886/docs/research/P1P2/anthropic-sdk.md

@@ -1,174 +0,0 @@
-# Anthropic SDK Research
-
-## Official Documentation URLs
-
-| Resource | URL |
-|----------|-----|
-| **NPM Package** | https://www.npmjs.com/package/@anthropic-ai/sdk |
-| **GitHub Repository** | https://github.com/anthropics/anthropic-sdk-typescript |
-| **API Reference** | https://github.com/anthropics/anthropic-sdk-typescript/blob/main/api.md |
-| **Helpers Documentation** | https://github.com/anthropics/anthropic-sdk-typescript/blob/main/helpers.md |
-| **Tool Use Guide** | https://platform.claude.com/docs/en/agents-and-tools/tool-use/implement-tool-use |
-| **Streaming Messages** | https://platform.claude.com/docs/en/api/messages-streaming |
-
-## Key TypeScript Interfaces
-
-### MessageCreateParams
-```typescript
-import Anthropic from '@anthropic-ai/sdk';
-
-const params: Anthropic.MessageCreateParams = {
-  model: 'claude-sonnet-4-20250514',
-  max_tokens: 1024,
-  messages: [{ role: 'user', content: 'Hello, Claude' }],
-  system?: string,
-  tools?: Tool[],
-  temperature?: number,
-  stop_sequences?: string[],
-};
-```
-
-### Message (Response)
-```typescript
-interface Message {
-  id: string;
-  type: 'message';
-  role: 'assistant';
-  model: string;
-  content: ContentBlock[];
-  stop_reason: 'end_turn' | 'tool_use' | 'max_tokens' | 'stop_sequence';
-  stop_sequence: string | null;
-  usage: {
-    input_tokens: number;
-    output_tokens: number;
-  };
-}
-```
-
-### ContentBlock Types
-```typescript
-type ContentBlock = TextBlock | ToolUseBlock;
-
-interface TextBlock {
-  type: 'text';
-  text: string;
-}
-
-interface ToolUseBlock {
-  type: 'tool_use';
-  id: string;
-  name: string;
-  input: Record<string, unknown>;
-}
-```
-
-### Tool Definition
-```typescript
-interface Tool {
-  name: string;
-  description: string;
-  input_schema: {
-    type: 'object';
-    properties: Record<string, unknown>;
-    required?: string[];
-  };
-}
-```
-
-## Tool Use Pattern
-
-### Define Tools
-```typescript
-const tools: Anthropic.Tool[] = [{
-  name: 'get_weather',
-  description: 'Get the current weather in a given location',
-  input_schema: {
-    type: 'object',
-    properties: {
-      location: { type: 'string', description: 'City name' }
-    },
-    required: ['location']
-  }
-}];
-```
-
-### Handle Tool Use Response
-```typescript
-if (response.stop_reason === 'tool_use') {
-  const toolUses = response.content.filter(
-    (block) => block.type === 'tool_use'
-  ) as Anthropic.ToolUseBlock[];
-
-  // Execute tools and return results
-  const toolResults = toolUses.map(toolUse => ({
-    type: 'tool_result' as const,
-    tool_use_id: toolUse.id,
-    content: executeToolAndGetResult(toolUse)
-  }));
-
-  // Continue conversation with tool results
-  const finalResponse = await client.messages.create({
-    model: 'claude-sonnet-4-20250514',
-    max_tokens: 1024,
-    tools,
-    messages: [
-      { role: 'user', content: originalMessage },
-      { role: 'assistant', content: response.content },
-      { role: 'user', content: toolResults }
-    ]
-  });
-}
-```
-
-## Streaming API
-
-```typescript
-const stream = await client.messages.stream({
-  model: 'claude-sonnet-4-20250514',
-  max_tokens: 1024,
-  messages: [{ role: 'user', content: 'Hello' }]
-});
-
-for await (const event of stream) {
-  switch (event.type) {
-    case 'message_start':
-    case 'content_block_start':
-    case 'content_block_delta':
-    case 'content_block_stop':
-    case 'message_delta':
-    case 'message_stop':
-  }
-}
-
-// Or use helper methods
-for await (const text of stream.textStream) {
-  process.stdout.write(text);
-}
-```
-
-## Error Handling
-
-```typescript
-import Anthropic from '@anthropic-ai/sdk';
-
-const client = new Anthropic({
-  apiKey: process.env.ANTHROPIC_API_KEY,
-  maxRetries: 2
-});
-
-try {
-  const response = await client.messages.create(params);
-} catch (error) {
-  if (error instanceof Anthropic.RateLimitError) {
-    // Handle rate limiting with retry-after header
-  } else if (error instanceof Anthropic.APIError) {
-    // Handle API errors
-  }
-}
-```
-
-## SDK Requirements
-
-- **TypeScript**: 4.9+
-- **Node.js**: 18+ (20 LTS recommended)
-- **Package Version**: @anthropic-ai/sdk@^0.71.1

package/plan/001_d3bb02af4886/docs/research/P1P2/async-local-storage.md

@@ -1,200 +0,0 @@
-# AsyncLocalStorage Research
-
-## Official Documentation URLs
-
-| Resource | URL |
-|----------|-----|
-| **Node.js Async Context** | https://nodejs.org/api/async_context.html |
-| **async_hooks Module** | https://nodejs.org/api/async_hooks.html |
-
-## Core API Methods
-
-### Creating Instance
-```typescript
-import { AsyncLocalStorage } from 'node:async_hooks';
-
-interface WorkflowContext {
-  executionId: string;
-  agentId: string;
-  stepName: string;
-}
-
-const workflowContext = new AsyncLocalStorage<WorkflowContext>();
-```
-
-### Establishing Context with .run()
-```typescript
-const result = await workflowContext.run(
-  { executionId: 'exec-123', agentId: 'agent-1', stepName: 'init' },
-  async () => {
-    // Context is active here and in all nested async calls
-    const store = workflowContext.getStore();
-    console.log(store.executionId); // 'exec-123'
-
-    await someAsyncOperation(); // Context propagates automatically
-    return 'completed';
-  }
-);
-```
-
-### Accessing Context with .getStore()
-```typescript
-function doSomething() {
-  const store = workflowContext.getStore();
-  if (store === undefined) {
-    throw new Error('Called outside workflow context');
-  }
-  console.log(`Execution: ${store.executionId}`);
-}
-```
-
-### Other Methods
-```typescript
-// enterWith - persist context for sync execution
-workflowContext.enterWith(store);
-
-// exit - run code outside context
-workflowContext.exit(() => {
-  workflowContext.getStore(); // undefined
-});
-
-// snapshot - capture context for later use
-const captured = workflowContext.run(123, () =>
-  workflowContext.snapshot()
-);
-
-// disable - disable instance
-workflowContext.disable();
-```
-
-## Usage Pattern for Agent/Prompt Context
-
-### Workflow Step Context Propagation
-```typescript
-const workflowContext = new AsyncLocalStorage<WorkflowContext>();
-
-// In workflow orchestrator
-async function executeWorkflow(workflow: Workflow) {
-  const context: WorkflowContext = {
-    executionId: generateId(),
-    workflowId: workflow.id,
-    agentId: workflow.agentId,
-    timestamp: Date.now()
-  };
-
-  return workflowContext.run(context, async () => {
-    // All nested calls automatically inherit context
-    await workflow.execute();
-  });
-}
-
-// In Agent.prompt() - automatically has access to context
-class Agent {
-  async prompt(message: string): Promise<string> {
-    const context = workflowContext.getStore();
-    if (!context) {
-      // Standalone call - no workflow context
-      return await this.callLLMStandalone(message);
-    }
-
-    // Automatically includes execution context
-    return await this.callLLMWithContext(message, context);
-  }
-}
-```
-
-### Nested Context Updates
-```typescript
-async function executeStep(step: WorkflowStep, parentContext: WorkflowContext) {
-  const stepContext: WorkflowContext = {
-    ...parentContext,
-    stepName: step.name,
-    metadata: {
-      ...parentContext.metadata,
-      stepStartTime: Date.now()
-    }
-  };
-
-  return workflowContext.run(stepContext, () => step.execute());
-}
-```
-
-## Best Practices
-
-### Performance
-- Overhead is < 10%, acceptable for most applications
-- Do NOT create more than 10-15 instances per application
-- Create ONE global instance per logical context type
-
-```typescript
-// Good: Single shared instance
-export const workflowContext = new AsyncLocalStorage<WorkflowContext>();
-
-// Bad: Creating instances per request
-const context = new AsyncLocalStorage(); // Don't do this
-```
-
-### Error Handling
-```typescript
-// Errors propagate correctly
-try {
-  workflowContext.run({ data: 'test' }, () => {
-    throw new Error('Something went wrong');
-  });
-} catch (e) {
-  // Error thrown, context auto-exits
-}
-
-// Always check for undefined
-function requireContext<T>(als: AsyncLocalStorage<T>, op: string): T {
-  const store = als.getStore();
-  if (store === undefined) {
-    throw new Error(`${op} called outside context`);
-  }
-  return store;
-}
-```
-
-### TypeScript Integration
-```typescript
-export const executionContext = new AsyncLocalStorage<ExecutionContext>();
-
-// Type-safe getter
-export function getExecutionContext(): ExecutionContext {
-  const context = executionContext.getStore();
-  if (!context) {
-    throw new Error('Execution context not available');
-  }
-  return context;
-}
-
-// Type-safe runner
-export async function runInContext<T>(
-  context: ExecutionContext,
-  fn: () => Promise<T>
-): Promise<T> {
-  return executionContext.run(context, fn);
-}
-```
-
-## Testing Patterns
-
-```typescript
-describe('Agent with Context', () => {
-  it('should have access to execution context', async () => {
-    const testContext = { executionId: 'test-123', agentId: 'agent-1' };
-
-    const result = await executionContext.run(testContext, async () => {
-      return await agent.prompt('test message');
-    });
-
-    expect(result).toBeDefined();
-  });
-
-  it('should throw when called outside context', async () => {
-    await expect(agent.prompt('test')).rejects.toThrow(
-      'Execution context not available'
-    );
-  });
-});
-```