anchi-toolkit 1.2.0 → 1.2.1

package/dist/skills/debugging/references/systematic-debugging.md

@@ -0,0 +1,102 @@
+# Systematic Debugging
+
+Four-phase debugging framework that ensures root cause investigation before attempting fixes.
+
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+If haven't completed Phase 1, cannot propose fixes.
+
+## The Four Phases
+
+Must complete each phase before proceeding to next.
+
+### Phase 1: Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+
+1. **Read Error Messages Carefully** - Don't skip past errors/warnings, read stack traces completely
+2. **Reproduce Consistently** - Can trigger reliably? Exact steps? If not reproducible → gather more data
+3. **Check Recent Changes** - What changed? Git diff, recent commits, new dependencies, config changes
+4. **Gather Evidence in Multi-Component Systems**
+   - For EACH component boundary: log data entering/exiting, verify environment propagation
+   - Run once to gather evidence showing WHERE it breaks
+   - THEN analyze to identify failing component
+5. **Trace Data Flow** - Where does bad value originate? Trace up call stack until finding source (see root-cause-tracing.md)
+
+### Phase 2: Pattern Analysis
+
+**Find pattern before fixing:**
+
+1. **Find Working Examples** - Locate similar working code in same codebase
+2. **Compare Against References** - Read reference implementation COMPLETELY, understand fully before applying
+3. **Identify Differences** - List every difference however small, don't assume "that can't matter"
+4. **Understand Dependencies** - What other components, settings, config, environment needed?
+
+### Phase 3: Hypothesis and Testing
+
+**Scientific method:**
+
+1. **Form Single Hypothesis** - "I think X is root cause because Y", be specific not vague
+2. **Test Minimally** - SMALLEST possible change to test hypothesis, one variable at a time
+3. **Verify Before Continuing** - Worked? → Phase 4. Didn't work? → NEW hypothesis. DON'T add more fixes
+4. **When Don't Know** - Say "I don't understand X", don't pretend, ask for help
+
+### Phase 4: Implementation
+
+**Fix root cause, not symptom:**
+
+1. **Create Failing Test Case** - Simplest reproduction, automated if possible, MUST have before fixing
+2. **Implement Single Fix** - Address root cause identified, ONE change, no "while I'm here" improvements
+3. **Verify Fix** - Test passes? No other tests broken? Issue actually resolved?
+4. **If Fix Doesn't Work**
+   - STOP. Count: How many fixes tried?
+   - If < 3: Return to Phase 1, re-analyze with new information
+   - **If ≥ 3: STOP and question architecture**
+5. **If 3+ Fixes Failed: Question Architecture**
+   - Pattern: Each fix reveals new shared state/coupling problem elsewhere
+   - STOP and question fundamentals: Is pattern sound? Wrong architecture?
+   - Discuss with human partner before more fixes
+
+## Red Flags - STOP and Follow Process
+
+If catch yourself thinking:
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "Add multiple changes, run tests"
+- "Skip the test, I'll manually verify"
+- "It's probably X, let me fix that"
+- "I don't fully understand but this might work"
+- "One more fix attempt" (when already tried 2+)
+
+**ALL mean:** STOP. Return to Phase 1.
+
+## Human Partner Signals You're Doing It Wrong
+
+- "Is that not happening?" - Assumed without verifying
+- "Will it show us...?" - Should have added evidence gathering
+- "Stop guessing" - Proposing fixes without understanding
+- "Ultrathink this" - Question fundamentals, not just symptoms
+- "We're stuck?" (frustrated) - Approach isn't working
+
+**When see these:** STOP. Return to Phase 1.
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Issue is simple, don't need process" | Simple issues have root causes too |
+| "Emergency, no time for process" | Systematic is FASTER than guess-and-check |
+| "Just try this first, then investigate" | First fix sets pattern. Do right from start |
+| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem |
+
+## Real-World Impact
+
+From debugging sessions:
+- Systematic approach: 15-30 minutes to fix
+- Random fixes approach: 2-3 hours of thrashing
+- First-time fix rate: 95% vs 40%
+- New bugs introduced: Near zero vs common

package/dist/skills/debugging/references/verification.md

@@ -0,0 +1,123 @@
+# Verification Before Completion
+
+Run verification commands and confirm output before claiming success.
+
+## Core Principle
+
+**Evidence before claims, always.**
+
+Claiming work complete without verification is dishonesty, not efficiency.
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If haven't run verification command in this message, cannot claim it passes.
+
+## The Gate Function
+
+```
+BEFORE claiming any status or expressing satisfaction:
+
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm claim?
+   - If NO: State actual status with evidence
+   - If YES: State claim WITH evidence
+5. ONLY THEN: Make claim
+
+Skip any step = lying, not verifying
+```
+
+## Common Failures
+
+| Claim | Requires | Not Sufficient |
+|-------|----------|----------------|
+| Tests pass | Test command output: 0 failures | Previous run, "should pass" |
+| Linter clean | Linter output: 0 errors | Partial check, extrapolation |
+| Build succeeds | Build command: exit 0 | Linter passing, logs look good |
+| Bug fixed | Test original symptom: passes | Code changed, assumed fixed |
+| Regression test works | Red-green cycle verified | Test passes once |
+| Agent completed | VCS diff shows changes | Agent reports "success" |
+| Requirements met | Line-by-line checklist | Tests passing |
+
+## Red Flags - STOP
+
+- Using "should", "probably", "seems to"
+- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!")
+- About to commit/push/PR without verification
+- Trusting agent success reports
+- Relying on partial verification
+- Thinking "just this once"
+- Tired and wanting work over
+- **ANY wording implying success without having run verification**
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "Should work now" | RUN verification |
+| "I'm confident" | Confidence ≠ evidence |
+| "Just this once" | No exceptions |
+| "Linter passed" | Linter ≠ compiler |
+| "Agent said success" | Verify independently |
+| "Partial check is enough" | Partial proves nothing |
+
+## Key Patterns
+
+**Tests:**
+```
+✅ [Run test command] [See: 34/34 pass] "All tests pass"
+❌ "Should pass now" / "Looks correct"
+```
+
+**Regression tests (TDD Red-Green):**
+```
+✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
+❌ "I've written regression test" (without red-green verification)
+```
+
+**Build:**
+```
+✅ [Run build] [See: exit 0] "Build passes"
+❌ "Linter passed" (linter doesn't check compilation)
+```
+
+**Requirements:**
+```
+✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
+❌ "Tests pass, phase complete"
+```
+
+**Agent delegation:**
+```
+✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
+❌ Trust agent report
+```
+
+## When To Apply
+
+**ALWAYS before:**
+- ANY variation of success/completion claims
+- ANY expression of satisfaction
+- ANY positive statement about work state
+- Committing, PR creation, task completion
+- Moving to next task
+- Delegating to agents
+
+**Rule applies to:**
+- Exact phrases
+- Paraphrases and synonyms
+- Implications of success
+- ANY communication suggesting completion/correctness
+
+## The Bottom Line
+
+**No shortcuts for verification.**
+
+Run command. Read output. THEN claim result.
+
+Non-negotiable.

package/dist/skills/debugging/scripts/find-polluter.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+# Bisection script to find which test creates unwanted files/state
+# Usage: ./find-polluter.sh <file_or_dir_to_check> <test_pattern>
+# Example: ./find-polluter.sh '.git' 'src/**/*.test.ts'
+
+set -e
+
+if [ $# -ne 2 ]; then
+  echo "Usage: $0 <file_to_check> <test_pattern>"
+  echo "Example: $0 '.git' 'src/**/*.test.ts'"
+  exit 1
+fi
+
+POLLUTION_CHECK="$1"
+TEST_PATTERN="$2"
+
+echo "🔍 Searching for test that creates: $POLLUTION_CHECK"
+echo "Test pattern: $TEST_PATTERN"
+echo ""
+
+# Get list of test files
+TEST_FILES=$(find . -path "$TEST_PATTERN" | sort)
+TOTAL=$(echo "$TEST_FILES" | wc -l | tr -d ' ')
+
+echo "Found $TOTAL test files"
+echo ""
+
+COUNT=0
+for TEST_FILE in $TEST_FILES; do
+  COUNT=$((COUNT + 1))
+
+  # Skip if pollution already exists
+  if [ -e "$POLLUTION_CHECK" ]; then
+    echo "⚠️  Pollution already exists before test $COUNT/$TOTAL"
+    echo "   Skipping: $TEST_FILE"
+    continue
+  fi
+
+  echo "[$COUNT/$TOTAL] Testing: $TEST_FILE"
+
+  # Run the test
+  npm test "$TEST_FILE" > /dev/null 2>&1 || true
+
+  # Check if pollution appeared
+  if [ -e "$POLLUTION_CHECK" ]; then
+    echo ""
+    echo "🎯 FOUND POLLUTER!"
+    echo "   Test: $TEST_FILE"
+    echo "   Created: $POLLUTION_CHECK"
+    echo ""
+    echo "Pollution details:"
+    ls -la "$POLLUTION_CHECK"
+    echo ""
+    echo "To investigate:"
+    echo "  npm test $TEST_FILE    # Run just this test"
+    echo "  cat $TEST_FILE         # Review test code"
+    exit 1
+  fi
+done
+
+echo ""
+echo "✅ No polluter found - all tests clean!"
+exit 0

package/dist/skills/debugging/scripts/find-polluter.test.md

@@ -0,0 +1,102 @@
+# find-polluter.sh Test Documentation
+
+## Purpose
+Bisection script to find which test creates unwanted files or state pollution.
+
+## Manual Test Procedure
+
+### Setup Test Scenario
+```bash
+# Create test directory
+mkdir -p /tmp/polluter-test && cd /tmp/polluter-test
+
+# Create clean test
+cat > test1.test.js << 'EOF'
+console.log('Test 1: clean');
+EOF
+
+# Create polluter test
+cat > test2.test.js << 'EOF'
+const fs = require('fs');
+fs.mkdirSync('.git', { recursive: true });
+console.log('Test 2: creates pollution');
+EOF
+
+# Create another clean test
+cat > test3.test.js << 'EOF'
+console.log('Test 3: clean');
+EOF
+```
+
+### Run Script
+```bash
+# For projects with npm test
+/path/to/find-polluter.sh '.git' 'src/**/*.test.ts'
+
+# For node-only tests (modify script to use 'node' instead of 'npm test')
+./find-polluter.sh '.git' '*.test.js'
+```
+
+### Expected Output
+```
+🔍 Searching for test that creates: .git
+Test pattern: *.test.js
+
+Found 3 test files
+
+[1/3] Testing: ./test1.test.js
+[2/3] Testing: ./test2.test.js
+
+🎯 FOUND POLLUTER!
+   Test: ./test2.test.js
+   Created: .git
+```
+
+### Cleanup
+```bash
+rm -rf /tmp/polluter-test
+```
+
+## Test Results
+
+✅ Script logic verified (2025-11-11)
+- Correctly iterates through test files
+- Detects pollution creation
+- Reports the polluting test file
+- Exits early when polluter found
+
+## Usage Notes
+
+**Prerequisites:**
+- Test runner (npm test) must be configured in project
+- Test pattern must match actual test files
+- Pollution path must be accurate
+
+**Customization:**
+If your project doesn't use `npm test`, modify line 42:
+```bash
+# Replace
+npm test "$TEST_FILE" > /dev/null 2>&1 || true
+
+# With your test command
+node "$TEST_FILE" > /dev/null 2>&1 || true
+# Or
+jest "$TEST_FILE" > /dev/null 2>&1 || true
+```
+
+## Common Use Cases
+
+1. **Find test creating .git directory:**
+   ```bash
+   ./find-polluter.sh '.git' 'src/**/*.test.ts'
+   ```
+
+2. **Find test creating node_modules:**
+   ```bash
+   ./find-polluter.sh 'node_modules' 'test/**/*.spec.js'
+   ```
+
+3. **Find test creating specific file:**
+   ```bash
+   ./find-polluter.sh 'unwanted-file.txt' '**/*.test.js'
+   ```

package/dist/skills/devops/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: devops
+description: Deploy and manage cloud infrastructure on Cloudflare (Workers, R2, D1, KV, Pages, Durable Objects, Browser Rendering), Docker containers, and Google Cloud Platform (Compute Engine, GKE, Cloud Run, App Engine, Cloud Storage). Use when deploying serverless functions to the edge, configuring edge computing solutions, managing Docker containers and images, setting up CI/CD pipelines, optimizing cloud infrastructure costs, implementing global caching strategies, working with cloud databases, or building cloud-native applications.
+license: MIT
+version: 1.0.0
+---
+
+# DevOps Skill
+
+Comprehensive guide for deploying and managing cloud infrastructure across Cloudflare edge platform, Docker containerization, and Google Cloud Platform.
+
+## When to Use This Skill
+
+Use this skill when:
+- Deploying serverless applications to Cloudflare Workers
+- Containerizing applications with Docker
+- Managing Google Cloud infrastructure with gcloud CLI
+- Setting up CI/CD pipelines across platforms
+- Optimizing cloud infrastructure costs
+- Implementing multi-region deployments
+- Building edge-first architectures
+- Managing container orchestration with Kubernetes
+- Configuring cloud storage solutions (R2, Cloud Storage)
+- Automating infrastructure with scripts and IaC
+
+## Platform Selection Guide
+
+### When to Use Cloudflare
+
+**Best For:**
+- Edge-first applications with global distribution
+- Ultra-low latency requirements (<50ms)
+- Static sites with serverless functions
+- Zero egress cost scenarios (R2 storage)
+- WebSocket/real-time applications (Durable Objects)
+- AI/ML at the edge (Workers AI)
+
+**Key Products:**
+- Workers (serverless functions)
+- R2 (object storage, S3-compatible)
+- D1 (SQLite database with global replication)
+- KV (key-value store)
+- Pages (static hosting + functions)
+- Durable Objects (stateful compute)
+- Browser Rendering (headless browser automation)
+
+**Cost Profile:** Pay-per-request, generous free tier, zero egress fees
+
+### When to Use Docker
+
+**Best For:**
+- Local development consistency
+- Microservices architectures
+- Multi-language stack applications
+- Traditional VPS/VM deployments
+- Kubernetes orchestration
+- CI/CD build environments
+- Database containerization (dev/test)
+
+**Key Capabilities:**
+- Application isolation and portability
+- Multi-stage builds for optimization
+- Docker Compose for multi-container apps
+- Volume management for data persistence
+- Network configuration and service discovery
+- Cross-platform compatibility (amd64, arm64)
+
+**Cost Profile:** Infrastructure cost only (compute + storage)
+
+### When to Use Google Cloud
+
+**Best For:**
+- Enterprise-scale applications
+- Data analytics and ML pipelines (BigQuery, Vertex AI)
+- Hybrid/multi-cloud deployments
+- Kubernetes at scale (GKE)
+- Managed databases (Cloud SQL, Firestore, Spanner)
+- Complex IAM and compliance requirements
+
+**Key Services:**
+- Compute Engine (VMs)
+- GKE (managed Kubernetes)
+- Cloud Run (containerized serverless)
+- App Engine (PaaS)
+- Cloud Storage (object storage)
+- Cloud SQL (managed databases)
+
+**Cost Profile:** Varied pricing, sustained use discounts, committed use contracts
+
+## Quick Start
+
+### Cloudflare Workers
+
+```bash
+# Install Wrangler CLI
+npm install -g wrangler
+
+# Create and deploy Worker
+wrangler init my-worker
+cd my-worker
+wrangler deploy
+```
+
+See: `references/cloudflare-workers-basics.md`
+
+### Docker Container
+
+```bash
+# Create Dockerfile
+cat > Dockerfile <<EOF
+FROM node:20-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --production
+COPY . .
+EXPOSE 3000
+CMD ["node", "server.js"]
+EOF
+
+# Build and run
+docker build -t myapp .
+docker run -p 3000:3000 myapp
+```
+
+See: `references/docker-basics.md`
+
+### Google Cloud Deployment
+
+```bash
+# Install and authenticate
+curl https://sdk.cloud.google.com | bash
+gcloud init
+gcloud auth login
+
+# Deploy to Cloud Run
+gcloud run deploy my-service \
+  --image gcr.io/project/image \
+  --region us-central1
+```
+
+See: `references/gcloud-platform.md`
+
+## Reference Navigation
+
+### Cloudflare Platform
+- `cloudflare-platform.md` - Edge computing overview, key components
+- `cloudflare-workers-basics.md` - Getting started, handler types, basic patterns
+- `cloudflare-workers-advanced.md` - Advanced patterns, performance, optimization
+- `cloudflare-workers-apis.md` - Runtime APIs, bindings, integrations
+- `cloudflare-r2-storage.md` - R2 object storage, S3 compatibility, best practices
+- `cloudflare-d1-kv.md` - D1 SQLite database, KV store, use cases
+- `browser-rendering.md` - Puppeteer/Playwright automation on Cloudflare
+
+### Docker Containerization
+- `docker-basics.md` - Core concepts, Dockerfile, images, containers
+- `docker-compose.md` - Multi-container apps, networking, volumes
+
+### Google Cloud Platform
+- `gcloud-platform.md` - GCP overview, gcloud CLI, authentication
+- `gcloud-services.md` - Compute Engine, GKE, Cloud Run, App Engine
+
+### Python Utilities
+- `scripts/cloudflare-deploy.py` - Automate Cloudflare Worker deployments
+- `scripts/docker-optimize.py` - Analyze and optimize Dockerfiles
+
+## Common Workflows
+
+### Edge + Container Hybrid
+
+```yaml
+# Cloudflare Workers (API Gateway)
+# -> Docker containers on Cloud Run (Backend Services)
+# -> R2 (Object Storage)
+
+# Benefits:
+# - Edge caching and routing
+# - Containerized business logic
+# - Global distribution
+```
+
+### Multi-Stage Docker Build
+
+```dockerfile
+# Build stage
+FROM node:20-alpine AS build
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+# Production stage
+FROM node:20-alpine
+WORKDIR /app
+COPY --from=build /app/dist ./dist
+COPY --from=build /app/node_modules ./node_modules
+USER node
+CMD ["node", "dist/server.js"]
+```
+
+### CI/CD Pipeline Pattern
+
+```yaml
+# 1. Build: Docker multi-stage build
+# 2. Test: Run tests in container
+# 3. Push: Push to registry (GCR, Docker Hub)
+# 4. Deploy: Deploy to Cloudflare Workers / Cloud Run
+# 5. Verify: Health checks and smoke tests
+```
+
+## Best Practices
+
+### Security
+- Run containers as non-root user
+- Use service account impersonation (GCP)
+- Store secrets in environment variables, not code
+- Scan images for vulnerabilities (Docker Scout)
+- Use API tokens with minimal permissions
+
+### Performance
+- Multi-stage Docker builds to reduce image size
+- Edge caching with Cloudflare KV
+- Use R2 for zero egress cost storage
+- Implement health checks for containers
+- Set appropriate timeouts and resource limits
+
+### Cost Optimization
+- Use Cloudflare R2 instead of S3 for large egress
+- Implement caching strategies (edge + KV)
+- Right-size container resources
+- Use sustained use discounts (GCP)
+- Monitor usage with cloud provider dashboards
+
+### Development
+- Use Docker Compose for local development
+- Wrangler dev for local Worker testing
+- Named gcloud configurations for multi-environment
+- Version control infrastructure code
+- Implement automated testing in CI/CD
+
+## Decision Matrix
+
+| Need | Choose |
+|------|--------|
+| Sub-50ms latency globally | Cloudflare Workers |
+| Large file storage (zero egress) | Cloudflare R2 |
+| SQL database (global reads) | Cloudflare D1 |
+| Containerized workloads | Docker + Cloud Run/GKE |
+| Enterprise Kubernetes | GKE |
+| Managed relational DB | Cloud SQL |
+| Static site + API | Cloudflare Pages |
+| WebSocket/real-time | Cloudflare Durable Objects |
+| ML/AI pipelines | GCP Vertex AI |
+| Browser automation | Cloudflare Browser Rendering |
+
+## Resources
+
+- **Cloudflare Docs:** https://developers.cloudflare.com
+- **Docker Docs:** https://docs.docker.com
+- **GCP Docs:** https://cloud.google.com/docs
+- **Wrangler CLI:** https://developers.cloudflare.com/workers/wrangler/
+- **gcloud CLI:** https://cloud.google.com/sdk/gcloud
+
+## Implementation Checklist
+
+### Cloudflare Workers
+- [ ] Install Wrangler CLI
+- [ ] Create Worker project
+- [ ] Configure wrangler.toml (bindings, routes)
+- [ ] Test locally with `wrangler dev`
+- [ ] Deploy with `wrangler deploy`
+
+### Docker
+- [ ] Write Dockerfile with multi-stage builds
+- [ ] Create .dockerignore file
+- [ ] Test build locally
+- [ ] Push to registry
+- [ ] Deploy to target platform
+
+### Google Cloud
+- [ ] Install gcloud CLI
+- [ ] Authenticate with service account
+- [ ] Create project and enable APIs
+- [ ] Configure IAM permissions
+- [ ] Deploy and monitor resources