@mohanscodex/spectra-code 0.4.9 → 0.5.0

package/skills/render-deploy/references/service-types.md

@@ -0,0 +1,450 @@
+# Render Service Types
+
+Detailed explanation of each service type available on Render. Choose the right service type based on your application's needs.
+
+## Web Services (`type: web`)
+
+### Purpose
+
+Web services are HTTP servers that handle incoming requests from the internet. They're publicly accessible via HTTPS URLs.
+
+### Use Cases
+
+- **REST APIs**: JSON APIs for mobile apps or frontend applications
+- **GraphQL servers**: GraphQL endpoints for client queries
+- **Web applications**: Server-rendered websites (Django, Rails, Express)
+- **Full-stack frameworks**: Next.js, Nuxt.js, Remix, SvelteKit
+- **WebSocket servers**: Real-time communication servers
+- **SSR applications**: Server-side rendered React, Vue, or Angular apps
+
+### Key Characteristics
+
+- **Public URL**: Automatically assigned `https://[service-name].onrender.com`
+- **Port binding required**: Must bind to `0.0.0.0:$PORT`
+- **Health checks**: Render pings your service to verify it's running
+- **HTTPS**: Automatic SSL/TLS certificates
+- **Load balancing**: Traffic distributed across multiple instances
+- **Custom domains**: Support for your own domain names
+
+### Required Configuration
+
+```yaml
+type: web
+name: my-api
+runtime: node
+buildCommand: npm ci
+startCommand: npm start
+```
+
+### Best Practices
+
+1. **Bind to environment PORT**:
+```javascript
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, '0.0.0.0');
+```
+
+2. **Add health check endpoint**:
+```javascript
+app.get('/health', (req, res) => {
+  res.status(200).json({ status: 'ok' });
+});
+```
+
+3. **Use appropriate timeouts**: Web requests should complete within 30 seconds
+
+4. **Implement graceful shutdown**: Handle SIGTERM signals properly
+
+---
+
+## Worker Services (`type: worker`)
+
+### Purpose
+
+Worker services run background tasks without handling HTTP requests. They're not publicly accessible.
+
+### Use Cases
+
+- **Queue processors**: Redis queue, BullMQ, Celery, Sidekiq
+- **Background jobs**: Email sending, image processing, data exports
+- **Event consumers**: Message queue consumers (Kafka, RabbitMQ, etc.)
+- **Data pipeline workers**: ETL processes, data transformation
+- **Scheduled background tasks**: Continuous processes (not cron)
+- **WebSocket backend**: Dedicated WebSocket handler services
+
+### Key Characteristics
+
+- **No public URL**: Not accessible from internet
+- **No port binding**: Doesn't need to listen on a port
+- **No health checks**: Render monitors process health differently
+- **Long-running**: Can run indefinitely
+- **Private communication**: Access via internal networking
+- **Restart on crash**: Automatically restarted if process dies
+
+### Required Configuration
+
+```yaml
+type: worker
+name: queue-processor
+runtime: python
+buildCommand: pip install -r requirements.txt
+startCommand: celery -A tasks worker --loglevel=info
+```
+
+### Best Practices
+
+1. **Connect to message queue**:
+```python
+import redis
+r = redis.from_url(os.environ['REDIS_URL'])
+```
+
+2. **Implement retry logic**: Handle failures gracefully
+
+3. **Monitor queue depth**: Track pending jobs
+
+4. **Log processing status**: Make debugging easier
+
+5. **Graceful shutdown**: Finish current jobs before exiting
+
+### Common Patterns
+
+**Node.js with BullMQ:**
+```yaml
+type: worker
+name: job-processor
+runtime: node
+buildCommand: npm ci
+startCommand: node worker.js
+envVars:
+  - key: REDIS_URL
+    fromDatabase:
+      name: redis
+      property: connectionString
+```
+
+**Python with Celery:**
+```yaml
+type: worker
+name: celery-worker
+runtime: python
+buildCommand: pip install -r requirements.txt
+startCommand: celery -A app.celery worker
+envVars:
+  - key: REDIS_URL
+    fromDatabase:
+      name: redis
+      property: connectionString
+```
+
+---
+
+## Cron Jobs (`type: cron`)
+
+### Purpose
+
+Cron jobs run scheduled tasks on a repeating schedule. They execute, complete, and shut down.
+
+### Use Cases
+
+- **Database backups**: Regular automated backups
+- **Report generation**: Daily/weekly reports
+- **Data cleanup**: Delete old records periodically
+- **Cache warming**: Pre-populate caches
+- **Email digests**: Send scheduled email summaries
+- **Data synchronization**: Sync between systems
+- **Batch processing**: Process accumulated data
+
+### Key Characteristics
+
+- **Scheduled execution**: Runs on cron schedule
+- **Automatic shutdown**: Shuts down after completing
+- **No persistent port**: Doesn't maintain listening port
+- **No health checks**: Task either completes or fails
+- **UTC timezone**: All schedules in UTC
+- **Maximum runtime**: Jobs timeout after configured limit
+
+### Required Configuration
+
+```yaml
+type: cron
+name: daily-backup
+runtime: node
+schedule: "0 2 * * *"  # Daily at 2 AM UTC
+buildCommand: npm ci
+startCommand: node scripts/backup.js
+```
+
+### Schedule Format
+
+Standard cron syntax: `minute hour day month weekday`
+
+**Common schedules:**
+
+| Schedule | Description |
+|----------|-------------|
+| `*/5 * * * *` | Every 5 minutes |
+| `0 * * * *` | Every hour |
+| `0 0 * * *` | Daily at midnight UTC |
+| `0 9 * * 1-5` | Weekdays at 9 AM UTC |
+| `0 0 1 * *` | First day of each month |
+| `0 9 * * 1` | Every Monday at 9 AM UTC |
+
+### Best Practices
+
+1. **Handle failures gracefully**: Jobs should be idempotent
+
+2. **Log completion status**: Track success/failure
+
+3. **Set appropriate timeouts**: Match expected job duration
+
+4. **Use UTC times**: All schedules are UTC-based
+
+5. **Test thoroughly**: Test with different data scenarios
+
+### Example Use Cases
+
+**Daily Database Backup:**
+```yaml
+type: cron
+name: db-backup
+runtime: python
+schedule: "0 1 * * *"  # 1 AM UTC daily
+buildCommand: pip install -r requirements.txt
+startCommand: python scripts/backup.py
+envVars:
+  - key: DATABASE_URL
+    fromDatabase:
+      name: postgres
+      property: connectionString
+  - key: S3_BUCKET
+    value: my-backups
+```
+
+**Hourly Cache Refresh:**
+```yaml
+type: cron
+name: cache-refresh
+runtime: node
+schedule: "0 * * * *"  # Top of every hour
+buildCommand: npm ci
+startCommand: node scripts/refresh-cache.js
+```
+
+---
+
+## Static Sites (`type: web` + `runtime: static`)
+
+### Purpose
+
+Serve static HTML, CSS, and JavaScript files via CDN. No backend runtime.
+
+### Use Cases
+
+- **Single Page Applications (SPAs)**: React, Vue, Angular apps
+- **Static site generators**: Gatsby, Next.js (static export), Hugo
+- **Documentation sites**: MkDocs, Docusaurus, VitePress
+- **Landing pages**: Marketing sites
+- **Portfolio sites**: Personal websites
+- **JAMstack sites**: Static sites with API integration
+
+### Key Characteristics
+
+- **CDN delivery**: Global edge caching
+- **No backend runtime**: Only serves built files
+- **Build output only**: Serves contents of build directory
+- **Routing support**: Rewrite rules for SPA routing
+- **Custom headers**: Cache control, security headers
+- **Fast deployment**: Quick to build and deploy
+
+### Required Configuration
+
+```yaml
+type: web
+name: frontend
+runtime: static
+buildCommand: npm ci && npm run build
+staticPublishPath: ./dist  # or ./build, ./out, ./public
+```
+
+### Routing for SPAs
+
+Single Page Applications need rewrite rules to handle client-side routing:
+
+```yaml
+type: web
+name: react-app
+runtime: static
+buildCommand: npm ci && npm run build
+staticPublishPath: ./build
+routes:
+  - type: rewrite
+    source: /*
+    destination: /index.html
+```
+
+### Custom Headers
+
+Add cache control and security headers:
+
+```yaml
+type: web
+name: static-site
+runtime: static
+buildCommand: npm ci && npm run build
+staticPublishPath: ./dist
+headers:
+  # Cache static assets
+  - path: /static/*
+    name: Cache-Control
+    value: public, max-age=31536000, immutable
+
+  # Security headers
+  - path: /*
+    name: X-Frame-Options
+    value: DENY
+  - path: /*
+    name: X-Content-Type-Options
+    value: nosniff
+```
+
+### Build Filters
+
+For monorepos, only build when frontend files change:
+
+```yaml
+type: web
+name: frontend
+runtime: static
+buildCommand: npm ci && npm run build
+staticPublishPath: ./dist
+buildFilter:
+  paths:
+    - frontend/**
+  ignoredPaths:
+    - frontend/**/*.test.js
+    - frontend/README.md
+```
+
+### Best Practices
+
+1. **Optimize build output**: Minify, compress, tree-shake
+
+2. **Use proper cache headers**: Long cache for hashed assets
+
+3. **Add security headers**: Protect against common attacks
+
+4. **Configure SPA routing**: Add rewrite rules for client routing
+
+5. **Handle 404s**: Create custom 404.html page
+
+---
+
+## Private Services (`type: pserv`)
+
+### Purpose
+
+Internal services accessible only within your Render account. Not exposed to the internet.
+
+### Use Cases
+
+- **Internal APIs**: Services accessed only by other services
+- **Database proxies**: Connection pools, read replicas
+- **Microservices**: Service mesh architectures
+- **Admin tools**: Internal dashboards
+- **Cache layers**: Internal caching services
+- **Message brokers**: Internal message queues
+
+### Key Characteristics
+
+- **No public URL**: Only accessible via internal DNS
+- **Internal networking**: Fast, low-latency connections
+- **Port binding required**: Must bind to `0.0.0.0:$PORT`
+- **Private DNS**: `[service-name].render-internal.com`
+- **Same-account only**: Only accessible from same account
+- **No internet access**: Traffic stays within Render network
+
+### Required Configuration
+
+```yaml
+type: pserv
+name: internal-api
+runtime: node
+buildCommand: npm ci
+startCommand: npm start
+```
+
+### Accessing Private Services
+
+From other services in the same account:
+
+```javascript
+// Use .render-internal.com domain
+const API_URL = 'http://internal-api.render-internal.com:10000';
+```
+
+Or use service references:
+
+```yaml
+services:
+  - type: web
+    name: frontend
+    runtime: node
+    envVars:
+      - key: INTERNAL_API_URL
+        fromService:
+          name: internal-api
+          type: pserv
+          property: hostport
+```
+
+### Best Practices
+
+1. **Use internal DNS**: Always use `.render-internal.com` domains
+
+2. **No authentication needed**: Already isolated to account
+
+3. **Fast communication**: Low latency between services
+
+4. **Simplify architecture**: No need for external load balancers
+
+---
+
+## Comparison Table
+
+| Feature | Web | Worker | Cron | Static | Private |
+|---------|-----|--------|------|--------|---------|
+| Public URL | ✅ Yes | ❌ No | ❌ No | ✅ Yes | ❌ No |
+| Port Binding | ✅ Required | ❌ Not needed | ❌ Not needed | ❌ N/A | ✅ Required |
+| Health Checks | ✅ Yes | ❌ No | ❌ No | ❌ N/A | ✅ Yes |
+| Runtime | ✅ Yes | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
+| Persistent | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes | ✅ Yes |
+| Scaling | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes | ✅ Yes |
+| Use Case | HTTP servers | Background jobs | Scheduled tasks | Static files | Internal services |
+
+## Choosing the Right Service Type
+
+**Use Web Service when:**
+- Your app handles HTTP requests
+- Users need to access it via URL
+- You need load balancing and scaling
+
+**Use Worker Service when:**
+- Processing background jobs
+- Consuming from message queues
+- Running long-lived processes without HTTP
+
+**Use Cron Job when:**
+- Running scheduled tasks
+- Processing doesn't need to be always-on
+- Tasks run periodically (hourly, daily, weekly)
+
+**Use Static Site when:**
+- Serving pre-built HTML/CSS/JS
+- No backend processing needed
+- Want CDN caching and fast delivery
+
+**Use Private Service when:**
+- Service only accessed by other services
+- Want internal-only communication
+- Building microservice architectures

package/skills/render-deploy/references/troubleshooting-basics.md

@@ -0,0 +1,36 @@
+# Basic troubleshooting (deploy-time and startup)
+
+Use this when a deploy fails, the service crashes on start, or health checks time out.
+Keep fixes minimal and redeploy after each change.
+
+## 1) Classify the failure
+
+- **Build failure**: errors in build logs, missing dependencies, build command issues.
+- **Startup failure**: app exits quickly, crashes, or cannot bind to `$PORT`.
+- **Runtime/health failure**: service is live but health checks fail or 5xx errors.
+
+## 2) Quick checks by class
+
+**Build failure**
+- Confirm the build command is correct for the runtime.
+- Ensure required dependencies are present in `package.json`, `requirements.txt`, etc.
+- Check for missing build-time env vars.
+
+**Startup failure**
+- Confirm the start command and working directory.
+- Ensure port binding is `0.0.0.0:$PORT`.
+- Check for missing runtime env vars (secrets, DB URLs).
+
+**Runtime/health failure**
+- Verify the health endpoint path and response.
+- Confirm the app is actually listening on `$PORT`.
+- Check database connectivity and migrations.
+
+## 3) Map error signatures to fixes
+
+Use [error-patterns.md](error-patterns.md) for a compact catalog of common log messages.
+
+## 4) If still blocked
+
+Gather the latest build logs and runtime error logs, then consider the optional
+`render-debug` skill for deeper diagnostics (metrics, DB checks, expanded patterns).

package/skills/research/ABOUT.md

@@ -0,0 +1,20 @@
+# Research Skills - Attribution
+
+This skill was derived from agent patterns in the [Amplifier](https://github.com/microsoft/amplifier) project.
+
+**Source Repository:**
+- Name: Amplifier
+- URL: https://github.com/microsoft/amplifier
+- Commit: 2adb63f858e7d760e188197c8e8d4c1ef721e2a6
+- Date: 2025-10-10
+
+## Skills Derived from Amplifier Agents
+
+**From knowledge-archaeologist agent:**
+- tracing-knowledge-lineages - Understanding how ideas evolved over time to find old solutions for new problems and avoid repeating past failures
+
+## What Was Adapted
+
+The knowledge-archaeologist agent excels at temporal analysis of knowledge evolution, paradigm shift documentation, and preserving the "fossil record" of ideas. This skill extracts the core research techniques for understanding why current approaches exist before proposing changes.
+
+Adapted with practical search strategies (decision records, git archaeology, conversation history) and scoped for mature codebases (explicitly notes to skip for greenfield projects).

package/skills/research/tracing-knowledge-lineages/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: Tracing Knowledge Lineages
+description: Understand how ideas evolved over time to find old solutions for new problems and avoid repeating past failures
+when_to_use: when questioning "why do we use X", before abandoning approaches, or evaluating "new" ideas that might be revivals
+version: 1.1.0
+---
+
+# Tracing Knowledge Lineages
+
+## Overview
+
+Ideas have history. Understanding why we arrived at current approaches - and what was tried before - prevents repeating failures and rediscovers abandoned solutions.
+
+**Core principle:** Before judging current approaches or proposing "new" ones, trace their lineage.
+
+## When to Trace Lineages
+
+**Trace before:**
+- Proposing to replace existing approach (understand why it exists first)
+- Dismissing "old" patterns (they might have been abandoned for wrong reasons)
+- Implementing "new" ideas (they might be revivals worth reconsidering)
+- Declaring something "best practice" (understand its evolution)
+
+**Red flags triggering lineage tracing:**
+- "This seems overcomplicated" (was it simpler before? why did it grow?)
+- "Why don't we just..." (someone probably tried, what happened?)
+- "This is the modern way" (what did the old way teach us?)
+- "We should switch to X" (what drove us away from X originally?)
+
+## Tracing Techniques
+
+### Technique 1: Decision Archaeology
+
+Search for when/why current approach was chosen:
+
+1. **Check decision records** (common locations: `docs/decisions/`, `docs/adr/`, `.decisions/`, architecture decision records)
+2. **Search conversations** (skills/collaboration/remembering-conversations)
+3. **Git archaeology** (`git log --all --full-history -- path/to/file`)
+4. **Ask the person who wrote it** (if available)
+
+**Document:**
+```markdown
+## Lineage: [Current Approach]
+
+**When adopted:** [Date/commit]
+**Why adopted:** [Original problem it solved]
+**What it replaced:** [Previous approach]
+**Why replaced:** [What was wrong with old approach]
+**Context that drove change:** [External factors, new requirements]
+```
+
+### Technique 2: Failed Attempt Analysis
+
+When someone says "we tried X and it didn't work":
+
+**Don't assume:** X is fundamentally flawed
+**Instead trace:**
+1. **What was the context?** (constraints that no longer apply)
+2. **What specifically failed?** (the whole approach or one aspect?)
+3. **Why did it fail then?** (technology limits, team constraints, time pressure)
+4. **Has context changed?** (new tools, different requirements, more experience)
+
+**Document:**
+```markdown
+## Failed Attempt: [Approach]
+
+**When attempted:** [Timeframe]
+**Why attempted:** [Original motivation]
+**What failed:** [Specific failure mode]
+**Why it failed:** [Root cause, not symptoms]
+**Context at time:** [Constraints that existed then]
+**Context now:** [What's different today]
+**Worth reconsidering?:** [Yes/No + reasoning]
+```
+
+### Technique 3: Revival Detection
+
+When evaluating "new" approaches:
+
+1. **Search for historical precedents** (was this tried before under different name?)
+2. **Identify what's genuinely new** (vs. what's rebranded)
+3. **Understand why it died** (if it's a revival)
+4. **Check if resurrection conditions exist** (has context changed enough?)
+
+**Common revival patterns:**
+- Microservices ← Service-Oriented Architecture ← Distributed Objects
+- GraphQL ← SOAP ← RPC
+- Serverless ← CGI scripts ← Cloud functions
+- NoSQL ← Flat files ← Document stores
+
+**Ask:** "What did we learn from the previous incarnation?"
+
+### Technique 4: Paradigm Shift Mapping
+
+When major architectural changes occurred:
+
+**Map the transition:**
+```markdown
+## Paradigm Shift: From [Old] to [New]
+
+**Pre-shift thinking:** [How we thought about problem]
+**Catalyst:** [What triggered the shift]
+**Post-shift thinking:** [How we think now]
+**What was gained:** [New capabilities]
+**What was lost:** [Old capabilities sacrificed]
+**Lessons preserved:** [What we kept from old paradigm]
+**Lessons forgotten:** [What we might need to relearn]
+```
+
+## Search Strategies
+
+**Where to look for lineage:**
+
+1. **Decision records** (common locations: `docs/decisions/`, `docs/adr/`, `.adr/`, or search for "ADR", "decision record")
+2. **Conversation history** (search with skills/collaboration/remembering-conversations)
+3. **Git history** (`git log --grep="keyword"`, `git blame`)
+4. **Issue/PR discussions** (GitHub/GitLab issue history)
+5. **Documentation evolution** (`git log -- docs/`)
+6. **Team knowledge** (ask: "Has anyone tried this before?")
+
+**Search patterns:**
+```bash
+# Find when approach was introduced
+git log --all --grep="introduce.*caching"
+
+# Find what file replaced
+git log --diff-filter=D --summary | grep pattern
+
+# Find discussion of abandoned approach
+git log --all --grep="remove.*websocket"
+```
+
+## Red Flags - You're Ignoring History
+
+- "Let's just rewrite this" (without understanding why it's complex)
+- "The old way was obviously wrong" (without understanding context)
+- "Nobody uses X anymore" (without checking why it died)
+- Dismissing approaches because they're "old" (age ≠ quality)
+- Adopting approaches because they're "new" (newness ≠ quality)
+
+**All of these mean: STOP. Trace the lineage first.**
+
+## When to Override History
+
+**You CAN ignore lineage when:**
+
+1. **Context fundamentally changed**
+   - Technology that didn't exist is now available
+   - Constraints that forced decisions no longer apply
+   - Team has different capabilities now
+
+2. **We learned critical lessons**
+   - Industry-wide understanding evolved
+   - Past attempt taught us what to avoid
+   - Better patterns emerged and were proven
+
+3. **Original reasoning was flawed**
+   - Based on assumptions later proven wrong
+   - Cargo-culting without understanding
+   - Fashion-driven, not needs-driven
+
+**But document WHY you're overriding:** Future you needs to know this was deliberate, not ignorant.
+
+## Documentation Format
+
+When proposing changes, include lineage:
+
+```markdown
+## Proposal: Switch from [Old] to [New]
+
+### Current Approach Lineage
+- **Adopted:** [When/why]
+- **Replaced:** [What it replaced]
+- **Worked because:** [Its strengths]
+- **Struggling because:** [Current problems]
+
+### Previous Attempts at [New]
+- **Attempted:** [When, if ever]
+- **Failed because:** [Why it didn't work then]
+- **Context change:** [What's different now]
+
+### Decision
+[Proceed/Defer/Abandon] because [reasoning with historical context]
+```
+
+## Examples
+
+### Good Lineage Tracing
+"We used XML before JSON. XML died because verbosity hurt developer experience. But XML namespaces solved a real problem. If we hit namespace conflicts in JSON, we should study how XML solved it, not reinvent."
+
+### Bad Lineage Ignorance
+"REST is old, let's use GraphQL." (Ignores: Why did REST win over SOAP? What problems does it solve well? Are those problems gone?)
+
+### Revival with Context
+"We tried client-side routing in 2010, abandoned it due to poor browser support. Now that support is universal and we have better tools, worth reconsidering with lessons learned."
+
+## Remember
+
+- Current approaches exist for reasons (trace those reasons)
+- Past failures might work now (context changes)
+- "New" approaches might be revivals (check for precedents)
+- Evolution teaches (study the transitions)
+- Ignorance of history = doomed to repeat it