mkdir -p /job-queue/product-{name}/research-notes

Write to: /job-queue/product-{name}/research-notes/stage1-research.md

# Big Idea: [Product Name]

## Product Overview
[2-3 paragraphs describing what the product does, who it's for, and why it matters]

## Core Value Proposition
[What makes this product unique or valuable]

## High-Level Architecture Approach
[Based on research, what architectural style makes sense?]
- Monolithic vs Microservices
- Serverless vs Server-based
- Event-driven vs Request-response
- [Any other key architectural decisions]

## Technology Landscape
[Summary of technology options researched]

### Frontend Options
- Option 1: [technology] - [pros/cons]
- Option 2: [technology] - [pros/cons]
- Option 3: [technology] - [pros/cons]

### Backend Options
- Option 1: [technology] - [pros/cons]
- Option 2: [technology] - [pros/cons]
- Option 3: [technology] - [pros/cons]

### Database Options
- Option 1: [technology] - [pros/cons]
- Option 2: [technology] - [pros/cons]

### Deployment Options
- Option 1: [platform] - [pros/cons]
- Option 2: [platform] - [pros/cons]

## Key Challenges Identified
1. [Challenge 1 and mitigation approach]
2. [Challenge 2 and mitigation approach]
3. [Challenge 3 and mitigation approach]

## Next Steps
- Deep dive into runtime execution patterns
- Research abstraction layer approaches
- Evaluate integration strategies
- Design output rendering pipeline

## Research Sources
[List of URLs and documentation consulted]

Write to: /job-queue/product-{name}/big-idea.md

You are researching runtime execution architecture for: [Product Name]

CONTEXT:
[Include big-idea.md content]

YOUR GOAL:
Create a comprehensive `runtime-execution.md` document that explains how the system executes work.

RESEARCH APPROACH:
1. Based on the technology options in big-idea.md, research each option's runtime model
2. Use WebSearch to find:
   - "[technology] runtime architecture 2026"
   - "[technology] execution model 2026"
   - "[technology] process lifecycle 2026"
   - "[technology] concurrency model 2026"

3. Use WebFetch to read official documentation for top candidates

4. Ask user clarifying questions about runtime preferences using AskUserQuestion

QUESTIONS TO ASK USER:

1. **Execution Model**
   - Header: "Execution"
   - Question: "How should the system execute work?"
   - Options:
     - "Request-response" - "Traditional HTTP request/response"
     - "Event-driven" - "Async processing with queues"
     - "Stream processing" - "Continuous data flow"
     - "Batch processing" - "Scheduled periodic jobs"

2. **Concurrency Needs**
   - Header: "Concurrency"
   - Question: "What concurrency model do you need?"
   - Options:
     - "Single-threaded async" - "Node.js style, high I/O"
     - "Multi-threaded" - "Python/Java threads, CPU work"
     - "Actor model" - "Erlang/Akka style isolation"
     - "Function-based" - "Serverless auto-scaling"

3. **State Management**
   - Header: "State"
   - Question: "How should runtime state be managed?"
   - Options:
     - "Stateless" - "No server-side state, scale easily"
     - "In-memory cache" - "Redis/Memcached for sessions"
     - "Persistent state" - "Database-backed state"
     - "Distributed state" - "Multi-node coordination"

DOCUMENT STRUCTURE:

Create: /job-queue/product-{name}/runtime-execution.md

# Runtime Execution Architecture

## Executive Summary
[2-3 paragraphs: What runtime model was chosen and why]

## Core Execution Engine

### Selected Technology
- **Primary Runtime**: [chosen technology]
- **Rationale**: [why this choice]
- **Trade-offs**: [what we're giving up]

### Execution Paradigm
[Describe: request-response, event-driven, streaming, batch]

## Process Lifecycle

### Initialization
[How the system starts up, bootstraps, loads config]

### Request Handling
[How incoming work is received and routed]

### Execution Flow
[Step-by-step: what happens when work arrives]

### Teardown/Cleanup
[How resources are released, graceful shutdown]

## State Management

### State Architecture
[Where state lives: memory, cache, database]

### State Lifecycle
[How state is created, updated, invalidated]

### State Consistency
[How consistency is maintained across requests]

## Concurrency Model

### Concurrency Approach
[Threads, async, actors, serverless]

### Parallelism Strategy
[How work is distributed across cores/nodes]

### Synchronization
[Locks, queues, coordination mechanisms]

## Hot-Reload & Dynamic Updates

### Development Experience
[Hot reload during dev? How does it work?]

### Production Updates
[Zero-downtime deploys? Blue-green? Rolling?]

## Resource Constraints & Optimization

### Memory Management
[How memory is allocated, GC considerations]

### CPU Utilization
[How CPU is used, optimization strategies]

### I/O Patterns
[Network, disk, database access patterns]

### Scaling Strategy
[Vertical vs horizontal, auto-scaling triggers]

## Technology Comparison

### Evaluated Options
| Technology | Pros | Cons | Fit Score |
|------------|------|------|-----------|
| [Tech 1]   | ...  | ...  | 8/10      |
| [Tech 2]   | ...  | ...  | 6/10      |
| [Tech 3]   | ...  | ...  | 4/10      |

### Decision Rationale
[Why we chose what we chose]

## Implementation Considerations

### Development Setup
[How to run locally]

### Testing Strategy
[How to test runtime behavior]

### Monitoring Needs
[What metrics to track]

## Research Sources
[URLs consulted during research]

---

After completing research and asking user questions, write this document to:
/job-queue/product-{name}/runtime-execution.md

Also save your raw research notes to:
/job-queue/product-{name}/research-notes/runtime-research.md

You are researching abstraction layer architecture for: [Product Name]

CONTEXT:
[Include big-idea.md content]

YOUR GOAL:
Create a comprehensive `abstraction-layer.md` document that explains how user intent translates to executable logic.

RESEARCH APPROACH:
1. Research how modern frameworks handle abstraction
2. Use WebSearch for:
   - "[technology] abstraction patterns 2026"
   - "[technology] DSL design 2026"
   - "no-code/low-code architecture 2026" (if applicable)
   - "[technology] configuration vs code 2026"

3. Use WebFetch to read architectural docs

4. Ask user clarifying questions

QUESTIONS TO ASK USER:

1. **Input Format**
   - Header: "Input"
   - Question: "How will users define what they want the system to do?"
   - Options:
     - "Code (APIs, SDKs)" - "Developer-focused, programmatic"
     - "Configuration (YAML, JSON)" - "Declarative configs"
     - "Visual interface (drag-drop)" - "No-code UI builder"
     - "Natural language" - "AI-powered interpretation"

2. **Translation Approach**
   - Header: "Translation"
   - Question: "How should user intent become executable code?"
   - Options:
     - "Direct interpretation" - "Runtime interpretation, flexible"
     - "Compilation to native" - "Compiled ahead-of-time, fast"
     - "IR/AST transformation" - "Intermediate representation"
     - "Template-based generation" - "Code generation from templates"

3. **Extensibility**
   - Header: "Extensibility"
   - Question: "How should users extend default behavior?"
   - Options:
     - "Plugin system" - "Loadable extensions"
     - "Hooks/callbacks" - "Event-based extension points"
     - "Subclassing/inheritance" - "OOP-style extension"
     - "Middleware/interceptors" - "Pipeline-based modification"

DOCUMENT STRUCTURE:

Create: /job-queue/product-{name}/abstraction-layer.md

# Abstraction Layer Architecture

## Executive Summary
[How user intent becomes executable logic]

## Input Formats

### Primary Input Method
[Code, config, visual, NLP]

### Input Schema
[Structure of input: JSON schema, API surface, grammar]

### Validation & Parsing
[How inputs are validated and parsed]

## Intermediate Representation

### IR Design
[AST, JSON schema, custom IR - what does it look like?]

### Why This IR
[Rationale for chosen representation]

### Example Transformation
[Show: input → IR → output]

## Translation Mechanisms

### Chosen Approach
[Interpretation vs compilation vs generation]

### Translation Pipeline
[Step-by-step: input → IR → executable]

### Optimization Passes
[Any optimization during translation?]

## Mapping Tables

### UI/Config → System Primitives
[How high-level concepts map to low-level operations]

### Example Mappings
| User Concept | System Primitive | Implementation |
|--------------|------------------|----------------|
| [Concept 1]  | [Primitive 1]    | [How it works] |

## Extension Points

### Extension Architecture
[Plugin system, hooks, inheritance]

### Extension Registration
[How extensions are discovered and loaded]

### Extension API
[What APIs are exposed to extensions]

### Example Extension
[Code sample showing how to extend]

## Trade-offs Analysis

### Flexibility vs Performance
[What we optimized for]

### Simplicity vs Power
[Where we drew the line]

### Developer Experience
[How easy is it to use?]

## Technology Comparison

### Evaluated Approaches
| Approach       | Flexibility | Performance | DX  | Chosen |
|----------------|-------------|-------------|-----|--------|
| [Approach 1]   | High        | Medium      | Low | ❌     |
| [Approach 2]   | Medium      | High        | High| ✅     |

## Implementation Considerations

### Schema Evolution
[How to version the abstraction layer]

### Backward Compatibility
[How to handle breaking changes]

### Documentation Strategy
[How users learn the abstraction]

## Research Sources
[URLs consulted]

---

Write to: /job-queue/product-{name}/abstraction-layer.md
Research notes: /job-queue/product-{name}/research-notes/abstraction-research.md

You are researching integration layer architecture for: [Product Name]

CONTEXT:
[Include big-idea.md content]

YOUR GOAL:
Create a comprehensive `integration-layer.md` document that explains how the system connects to external resources.

RESEARCH APPROACH:
1. Research connector patterns and integration architectures
2. Use WebSearch for:
   - "[technology] connector architecture 2026"
   - "API integration best practices 2026"
   - "[technology] authentication patterns 2026"
   - "service mesh architecture 2026" (if microservices)

3. Use WebFetch for vendor-specific docs (if integrating with known services)

4. Ask user clarifying questions

QUESTIONS TO ASK USER:

1. **Integration Scope**
   - Header: "Integrations"
   - Question: "What external systems will this product integrate with?"
   - MultiSelect: true
   - Options:
     - "Databases" - "PostgreSQL, MySQL, MongoDB, etc."
     - "APIs (REST/GraphQL)" - "External HTTP APIs"
     - "Message queues" - "RabbitMQ, Kafka, SQS, etc."
     - "Storage services" - "S3, GCS, Azure Storage"

2. **Authentication Strategy**
   - Header: "Auth"
   - Question: "How should the system authenticate to external services?"
   - Options:
     - "API keys" - "Simple token-based auth"
     - "OAuth 2.0" - "Delegated authorization"
     - "Mutual TLS" - "Certificate-based auth"
     - "Service accounts" - "Cloud provider IAM"

3. **Discovery Mechanism**
   - Header: "Discovery"
   - Question: "How should the system discover external services?"
   - Options:
     - "Static configuration" - "Hardcoded endpoints"
     - "Environment variables" - "Deploy-time config"
     - "Service discovery" - "Consul, Eureka, k8s DNS"
     - "Dynamic registry" - "Runtime service registration"

DOCUMENT STRUCTURE:

Create: /job-queue/product-{name}/integration-layer.md

# Integration Layer Architecture

## Executive Summary
[How the system connects to external resources]

## Connector Architecture

### Connector Pattern
[Plugin-based, driver-based, adapter pattern]

### Supported Protocols
- REST API
- GraphQL
- gRPC
- Message queues
- Database protocols
- Custom protocols

### Connector Lifecycle
[How connectors are initialized, used, closed]

## Authentication & Credential Management

### Authentication Methods
[API keys, OAuth, mTLS, service accounts]

### Credential Storage
[Where credentials live: env vars, secrets manager, vault]

### Rotation Strategy
[How credentials are rotated without downtime]

### Security Boundaries
[How credentials are isolated per service]

## Service Discovery

### Discovery Mechanism
[Static, env-based, service discovery, dynamic]

### Configuration Format
```json
{
  "services": {
    "database": {
      "type": "postgresql",
      "discovery": "static",
      "endpoint": "..."
    }
  }
}

{
  "retry": {
    "maxAttempts": 3,
    "backoff": "exponential",
    "initialDelay": "100ms"
  }
}

### Stage 5: Output Rendering Research (Agent 4)

**Agent task:**

1. Client subscribes to updates
2. Server pushes incremental changes
3. Client updates UI reactively

<Layout>
  <Header />
  <Main>
    <DataGrid data={...} />
  </Main>
  <Footer />
</Layout>

### Parallel Execution

**Launch all 4 agents at once:**

```bash
# Agent 1: Runtime Execution
Task tool:
  subagent_type: "general-purpose"
  description: "Runtime execution research"
  prompt: [Stage 2 agent task]

# Agent 2: Abstraction Layer
Task tool:
  subagent_type: "general-purpose"
  description: "Abstraction layer research"
  prompt: [Stage 3 agent task]

# Agent 3: Integration Layer
Task tool:
  subagent_type: "general-purpose"
  description: "Integration layer research"
  prompt: [Stage 4 agent task]

# Agent 4: Output Rendering
Task tool:
  subagent_type: "general-purpose"
  description: "Output rendering research"
  prompt: [Stage 5 agent task]

Read:
- /job-queue/product-{name}/big-idea.md
- /job-queue/product-{name}/runtime-execution.md
- /job-queue/product-{name}/abstraction-layer.md
- /job-queue/product-{name}/integration-layer.md
- /job-queue/product-{name}/output-rendering.md

# Architecture Summary: [Product Name]

## Research Completion

**Date:** [timestamp]
**Input:** [original input]
**Product Name:** [derived name]

## Recommended Architecture

### Technology Stack
- **Frontend**: [chosen technology]
- **Backend**: [chosen technology]
- **Database**: [chosen technology]
- **Deployment**: [chosen platform]

### Architectural Style
- [Monolithic/Microservices/Serverless]
- [Event-driven/Request-response]
- [SSR/CSR/SSG]

### Key Design Decisions

#### Runtime Execution
[1-2 sentence summary from runtime-execution.md]

#### Abstraction Layer
[1-2 sentence summary from abstraction-layer.md]

#### Integration Layer
[1-2 sentence summary from integration-layer.md]

#### Output Rendering
[1-2 sentence summary from output-rendering.md]

## Trade-offs & Risks

### Major Trade-offs
1. [Trade-off 1]: Chose X over Y because [reason]
2. [Trade-off 2]: Chose X over Y because [reason]

### Identified Risks
1. [Risk 1]: [Mitigation strategy]
2. [Risk 2]: [Mitigation strategy]

## Next Steps

To proceed with implementation:

1. Review detailed architecture documents:
   - `runtime-execution.md`
   - `abstraction-layer.md`
   - `integration-layer.md`
   - `output-rendering.md`

2. Set up development environment

3. Create initial project structure

4. Begin implementation with chosen tech stack

## Research Artifacts

All research is saved in:
- `/job-queue/product-{name}/`
- `/job-queue/product-{name}/research-notes/`

Total research sources consulted: [count]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎉 PRODUCT RESEARCH COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Product: [Product Name]
Location: /job-queue/product-{name}/

Generated Documents:
  ✅ big-idea.md              - High-level vision and approach
  ✅ runtime-execution.md     - How the system executes work
  ✅ abstraction-layer.md     - How user intent becomes logic
  ✅ integration-layer.md     - How system connects externally
  ✅ output-rendering.md      - How results are delivered
  ✅ ARCHITECTURE-SUMMARY.md  - Executive summary

Recommended Stack:
  Frontend:   [technology]
  Backend:    [technology]
  Database:   [technology]
  Deployment: [platform]

Research Sources: [count] URLs consulted

Next Steps:
  1. Review detailed architecture docs in /job-queue/product-{name}/
  2. Approve or request revisions
  3. Begin implementation

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

❌ Research Failed at Stage 3/6: Abstraction Layer

Completed:
  ✓ [Stage 0] Workspace created
  ✓ [Stage 1] Big idea generated
  ✓ [Stage 2] Runtime execution researched
  ✗ [Stage 3] Abstraction layer FAILED

Error: [error message]

Partial work saved at: /job-queue/product-{name}/

Recovery:
  - Fix the issue and resume with: /new-product [input]
  - Or manually continue research