groundswell 0.0.1

package/PRPs/templates/prp_base.md

@@ -0,0 +1,222 @@
+# PRP Template: {Feature Name}
+
+> **PRP**: Product Requirements Package - A comprehensive implementation guide enabling one-pass success
+
+## Pre-Implementation Checklist
+
+Before implementing, verify you have:
+- [ ] Read and understood this entire PRP
+- [ ] Access to all referenced files and documentation
+- [ ] Development environment properly configured
+- [ ] Understanding of existing codebase patterns
+
+---
+
+## 1. Goal
+
+### Feature Goal
+{One clear sentence describing what this feature accomplishes}
+
+### Deliverable
+{Concrete, measurable output - what files/functionality will exist when done}
+
+### Success Definition
+{How to verify the feature works correctly - specific criteria}
+
+---
+
+## 2. Context
+
+### External Documentation
+```yaml
+primary_docs:
+  - url: "{documentation_url}#specific-section"
+    purpose: "{what to learn from this}"
+    key_sections:
+      - "{section name}"
+
+reference_implementations:
+  - url: "{github_url}"
+    purpose: "{what patterns to follow}"
+    files_to_study:
+      - "{specific file path}"
+```
+
+### Codebase Context
+```yaml
+existing_patterns:
+  - file: "{path/to/file.ts}"
+    pattern: "{pattern name}"
+    follow_for: "{what aspect to replicate}"
+
+related_files:
+  - path: "{path/to/related.ts}"
+    relationship: "{how it relates to this feature}"
+
+naming_conventions:
+  files: "{convention description}"
+  classes: "{convention description}"
+  functions: "{convention description}"
+```
+
+### Technical Constraints
+```yaml
+typescript:
+  version: "{minimum version}"
+  config_requirements:
+    - "{specific tsconfig setting}"
+
+dependencies:
+  required:
+    - name: "{package name}"
+      version: "{version range}"
+      purpose: "{why needed}"
+  avoid:
+    - name: "{package to avoid}"
+      reason: "{why to avoid}"
+
+runtime:
+  node_version: "{minimum version}"
+  target: "{ES target}"
+```
+
+### Known Gotchas
+```yaml
+pitfalls:
+  - issue: "{description of common mistake}"
+    solution: "{how to avoid/fix}"
+
+  - issue: "{another common mistake}"
+    solution: "{how to avoid/fix}"
+```
+
+---
+
+## 3. Implementation Tasks
+
+> Tasks are ordered by dependency. Complete each task fully before moving to the next.
+
+### Task 1: {Task Name}
+**Depends on**: None (or list dependencies)
+
+**Input**: {What you need before starting}
+
+**Steps**:
+1. {Specific action with exact file names}
+2. {Next action}
+3. {Continue...}
+
+**Output**: {What should exist when done}
+
+**Validation**: {How to verify this task is complete}
+
+---
+
+### Task 2: {Task Name}
+**Depends on**: Task 1
+
+**Input**: {What you need}
+
+**Steps**:
+1. {Actions}
+
+**Output**: {Results}
+
+**Validation**: {Verification steps}
+
+---
+
+{Continue with additional tasks...}
+
+---
+
+## 4. Implementation Details
+
+### Code Patterns to Follow
+
+```typescript
+// Example pattern with annotations
+{code example showing the pattern to follow}
+```
+
+### File Structure
+```
+{directory structure showing where files should be created}
+```
+
+### Interface Definitions
+```typescript
+// Key interfaces that must be implemented
+{interface definitions}
+```
+
+---
+
+## 5. Testing Strategy
+
+### Unit Tests
+```yaml
+test_files:
+  - path: "{test file path}"
+    covers:
+      - "{what it tests}"
+
+test_patterns:
+  - "{describe the testing pattern to follow}"
+```
+
+### Integration Tests
+```yaml
+scenarios:
+  - name: "{test scenario}"
+    validates: "{what it validates}"
+```
+
+### Manual Validation
+```yaml
+steps:
+  - action: "{what to do}"
+    expected: "{expected result}"
+```
+
+---
+
+## 6. Final Validation Checklist
+
+### Code Quality
+- [ ] All TypeScript compiles without errors
+- [ ] No linting warnings
+- [ ] Follows existing code patterns
+- [ ] Proper error handling
+
+### Functionality
+- [ ] {Specific functional requirement}
+- [ ] {Another requirement}
+
+### Testing
+- [ ] Unit tests pass
+- [ ] Integration tests pass
+- [ ] Manual validation complete
+
+### Documentation
+- [ ] Code is self-documenting with clear names
+- [ ] Complex logic has comments
+- [ ] Public APIs have JSDoc
+
+---
+
+## 7. "No Prior Knowledge" Test
+
+**Validation**: If someone knew nothing about this codebase, would they have everything needed to implement this successfully using only this PRP?
+
+- [ ] All file paths are absolute and specific
+- [ ] All patterns have concrete examples
+- [ ] All dependencies are explicitly listed
+- [ ] All validation steps are executable
+- [ ] No assumed knowledge of codebase internals
+
+---
+
+## Confidence Score: {X}/10
+
+**Rationale**: {Brief explanation of confidence level and any remaining uncertainties}

package/README.md

@@ -0,0 +1,218 @@
+# Groundswell
+
+Hierarchical workflow orchestration engine with full observability.
+
+## Installation
+
+```bash
+npm install groundswell
+```
+
+**Requirements:** Node.js 18+, TypeScript 5.2+
+
+## Quick Start
+
+### Class-Based Workflow
+
+```typescript
+import { Workflow, Step, ObservedState, WorkflowTreeDebugger } from 'groundswell';
+
+class DataProcessor extends Workflow {
+  @ObservedState()
+  progress = 0;
+
+  @Step({ trackTiming: true, snapshotState: true })
+  async process(): Promise<string[]> {
+    this.progress = 100;
+    return ['item1', 'item2', 'item3'];
+  }
+
+  async run(): Promise<string[]> {
+    this.setStatus('running');
+    const result = await this.process();
+    this.setStatus('completed');
+    return result;
+  }
+}
+
+const workflow = new DataProcessor('DataProcessor');
+const debugger_ = new WorkflowTreeDebugger(workflow);
+
+const result = await workflow.run();
+console.log(debugger_.toTreeString());
+```
+
+### Functional Workflow
+
+```typescript
+import { createWorkflow } from 'groundswell';
+
+const workflow = createWorkflow(
+  { name: 'DataPipeline' },
+  async (ctx) => {
+    const loaded = await ctx.step('load', async () => fetchData());
+    const processed = await ctx.step('process', async () => transform(loaded));
+    return processed;
+  }
+);
+
+const result = await workflow.run();
+```
+
+### Agent with Prompt
+
+```typescript
+import { createAgent, createPrompt } from 'groundswell';
+import { z } from 'zod';
+
+const agent = createAgent({
+  name: 'AnalysisAgent',
+  enableCache: true,
+});
+
+const prompt = createPrompt({
+  user: 'Analyze this code for bugs',
+  data: { code: 'function foo() { return 42; }' },
+  responseFormat: z.object({
+    bugs: z.array(z.string()),
+    severity: z.enum(['low', 'medium', 'high']),
+  }),
+});
+
+const result = await agent.prompt(prompt);
+// result is typed as { bugs: string[], severity: 'low' | 'medium' | 'high' }
+```
+
+## Documentation
+
+- [Workflows](docs/workflow.md) - Hierarchical task orchestration
+- [Agents](docs/agent.md) - LLM execution with caching and reflection
+- [Prompts](docs/prompt.md) - Type-safe prompt definitions with Zod
+
+### For AI Agents
+
+Full documentation in a single file: [`llms_full.txt`](llms_full.txt)
+
+Generate with `npm run generate:llms`
+
+## Core Concepts
+
+### Workflows
+
+The primary orchestration unit. Manage execution status, emit events, and support hierarchical parent-child relationships. Two patterns are supported:
+- **Class-based**: Extend `Workflow` and override `run()`
+- **Functional**: Use `createWorkflow()` with an executor function
+
+### Agents
+
+Lightweight wrappers around the Anthropic SDK. Execute prompts, manage tool invocation cycles, and integrate with caching and reflection systems.
+
+### Prompts
+
+Immutable value objects defining what to send to an agent and how to validate the response using Zod schemas.
+
+## Decorators
+
+```typescript
+// Emit lifecycle events and track timing
+@Step({ trackTiming: true, snapshotState: true })
+async processData(): Promise<void> { }
+
+// Spawn and manage child workflows
+@Task({ concurrent: true })
+async createWorkers(): Promise<WorkerWorkflow[]> { }
+
+// Mark fields for state snapshots
+@ObservedState()
+progress: number = 0;
+
+@ObservedState({ redact: true })  // Shown as '***'
+apiKey: string = 'secret';
+```
+
+## Caching
+
+LLM responses are cached using deterministic SHA-256 keys:
+
+```typescript
+import { createAgent, defaultCache } from 'groundswell';
+
+const agent = createAgent({ enableCache: true });
+
+const result1 = await agent.prompt(prompt);  // API call
+const result2 = await agent.prompt(prompt);  // Cached
+
+console.log(defaultCache.metrics());  // { hits: 1, misses: 1, hitRate: 50 }
+```
+
+## Reflection
+
+Multi-level error recovery with automatic retry:
+
+```typescript
+const workflow = createWorkflow(
+  { name: 'MyWorkflow', enableReflection: true },
+  async (ctx) => {
+    await ctx.step('unreliable-operation', async () => {
+      // If this fails, reflection will analyze and retry
+    });
+  }
+);
+```
+
+## Introspection Tools
+
+Agents can inspect their position in the workflow hierarchy:
+
+```typescript
+import { INTROSPECTION_TOOLS, createAgent } from 'groundswell';
+
+const agent = createAgent({
+  name: 'IntrospectionAgent',
+  tools: INTROSPECTION_TOOLS,  // 6 tools for hierarchy navigation
+});
+```
+
+## Examples
+
+```bash
+npm run start:all              # Interactive runner
+npm run start:basic            # Basic workflow
+npm run start:decorators       # Decorator options
+npm run start:parent-child     # Hierarchical workflows
+npm run start:observers        # Observers and debugger
+npm run start:errors           # Error handling
+npm run start:concurrent       # Concurrent tasks
+npm run start:agent-loops      # Agent loops
+npm run start:sdk-features     # Tools, MCPs, hooks
+npm run start:reflection       # Multi-level reflection
+npm run start:introspection    # Introspection tools
+```
+
+See [examples/](examples/) for source code.
+
+## API Reference
+
+| Category | Exports |
+|----------|---------|
+| **Core** | `Workflow`, `Agent`, `Prompt`, `MCPHandler` |
+| **Factories** | `createWorkflow`, `createAgent`, `createPrompt` |
+| **Decorators** | `@Step`, `@Task`, `@ObservedState` |
+| **Caching** | `LLMCache`, `defaultCache`, `generateCacheKey` |
+| **Reflection** | `ReflectionManager`, `executeWithReflection` |
+| **Introspection** | `INTROSPECTION_TOOLS`, `handleInspectCurrentNode`, ... |
+| **Debugging** | `WorkflowTreeDebugger`, `Observable` |
+
+## Contributing
+
+Contributions and issues are welcome.
+
+## Support
+
+If Groundswell helps you build something great, consider fueling future development:
+
+<a href="https://buymeacoffee.com/dustindsch2" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="50"></a>
+
+## License
+
+MIT