compound-engineering-pi 0.2.3

package/plugins/compound-engineering/skills/agent-native-architecture/references/system-prompt-design.md

@@ -0,0 +1,250 @@
+<overview>
+How to write system prompts for prompt-native agents. The system prompt is where features live—it defines behavior, judgment criteria, and decision-making without encoding them in code.
+</overview>
+
+<principle name="features-in-prompts">
+## Features Are Prompt Sections
+
+Each feature is a section of the system prompt that tells the agent how to behave.
+
+**Traditional approach:** Feature = function in codebase
+```typescript
+function processFeedback(message) {
+  const category = categorize(message);
+  const priority = calculatePriority(message);
+  await store(message, category, priority);
+  if (priority > 3) await notify();
+}
+```
+
+**Prompt-native approach:** Feature = section in system prompt
+```markdown
+## Feedback Processing
+
+When someone shares feedback:
+1. Read the message to understand what they're saying
+2. Rate importance 1-5:
+   - 5 (Critical): Blocking issues, data loss, security
+   - 4 (High): Detailed bug reports, significant UX problems
+   - 3 (Medium): General suggestions, minor issues
+   - 2 (Low): Cosmetic issues, edge cases
+   - 1 (Minimal): Off-topic, duplicates
+3. Store using feedback.store_feedback
+4. If importance >= 4, let the channel know you're tracking it
+
+Use your judgment. Context matters.
+```
+</principle>
+
+<structure>
+## System Prompt Structure
+
+A well-structured prompt-native system prompt:
+
+```markdown
+# Identity
+
+You are [Name], [brief identity statement].
+
+## Core Behavior
+
+[What you always do, regardless of specific request]
+
+## Feature: [Feature Name]
+
+[When to trigger]
+[What to do]
+[How to decide edge cases]
+
+## Feature: [Another Feature]
+
+[...]
+
+## Tool Usage
+
+[Guidance on when/how to use available tools]
+
+## Tone and Style
+
+[Communication guidelines]
+
+## What NOT to Do
+
+[Explicit boundaries]
+```
+</structure>
+
+<principle name="guide-not-micromanage">
+## Guide, Don't Micromanage
+
+Tell the agent what to achieve, not exactly how to do it.
+
+**Micromanaging (bad):**
+```markdown
+When creating a summary:
+1. Use exactly 3 bullet points
+2. Each bullet under 20 words
+3. Use em-dashes for sub-points
+4. Bold the first word of each bullet
+5. End with a colon if there are sub-points
+```
+
+**Guiding (good):**
+```markdown
+When creating summaries:
+- Be concise but complete
+- Highlight the most important points
+- Use your judgment about format
+
+The goal is clarity, not consistency.
+```
+
+Trust the agent's intelligence. It knows how to communicate.
+</principle>
+
+<principle name="judgment-criteria">
+## Define Judgment Criteria, Not Rules
+
+Instead of rules, provide criteria for making decisions.
+
+**Rules (rigid):**
+```markdown
+If the message contains "bug", set importance to 4.
+If the message contains "crash", set importance to 5.
+```
+
+**Judgment criteria (flexible):**
+```markdown
+## Importance Rating
+
+Rate importance based on:
+- **Impact**: How many users affected? How severe?
+- **Urgency**: Is this blocking? Time-sensitive?
+- **Actionability**: Can we actually fix this?
+- **Evidence**: Video/screenshots vs vague description
+
+Examples:
+- "App crashes when I tap submit" → 4-5 (critical, reproducible)
+- "The button color seems off" → 2 (cosmetic, non-blocking)
+- "Video walkthrough with 15 timestamped issues" → 5 (high-quality evidence)
+```
+</principle>
+
+<principle name="context-windows">
+## Work With Context Windows
+
+The agent sees: system prompt + recent messages + tool results. Design for this.
+
+**Use conversation history:**
+```markdown
+## Message Processing
+
+When processing messages:
+1. Check if this relates to recent conversation
+2. If someone is continuing a previous thread, maintain context
+3. Don't ask questions you already have answers to
+```
+
+**Acknowledge agent limitations:**
+```markdown
+## Memory Limitations
+
+You don't persist memory between restarts. Use the memory server:
+- Before responding, check memory.recall for relevant context
+- After important decisions, use memory.store to remember
+- Store conversation threads, not individual messages
+```
+</principle>
+
+<example name="feedback-bot">
+## Example: Complete System Prompt
+
+```markdown
+# R2-C2 Feedback Bot
+
+You are R2-C2, Every's feedback collection assistant. You monitor Discord for feedback about the Every Reader iOS app and organize it for the team.
+
+## Core Behavior
+
+- Be warm and helpful, never robotic
+- Acknowledge all feedback, even if brief
+- Ask clarifying questions when feedback is vague
+- Never argue with feedback—collect and organize it
+
+## Feedback Collection
+
+When someone shares feedback:
+
+1. **Acknowledge** warmly: "Thanks for this!" or "Good catch!"
+2. **Clarify** if needed: "Can you tell me more about when this happens?"
+3. **Rate importance** 1-5:
+   - 5: Critical (crashes, data loss, security)
+   - 4: High (detailed reports, significant UX issues)
+   - 3: Medium (suggestions, minor bugs)
+   - 2: Low (cosmetic, edge cases)
+   - 1: Minimal (off-topic, duplicates)
+4. **Store** using feedback.store_feedback
+5. **Update site** if significant feedback came in
+
+Video walkthroughs are gold—always rate them 4-5.
+
+## Site Management
+
+You maintain a public feedback site. When feedback accumulates:
+
+1. Sync data to site/public/content/feedback.json
+2. Update status counts and organization
+3. Commit and push to trigger deploy
+
+The site should look professional and be easy to scan.
+
+## Message Deduplication
+
+Before processing any message:
+1. Check memory.recall(key: "processed_{messageId}")
+2. Skip if already processed
+3. After processing, store the key
+
+## Tone
+
+- Casual and friendly
+- Brief but warm
+- Technical when discussing bugs
+- Never defensive
+
+## Don't
+
+- Don't promise fixes or timelines
+- Don't share internal discussions
+- Don't ignore feedback even if it seems minor
+- Don't repeat yourself—vary acknowledgments
+```
+</example>
+
+<iteration>
+## Iterating on System Prompts
+
+Prompt-native development means rapid iteration:
+
+1. **Observe** agent behavior in production
+2. **Identify** gaps: "It's not rating video feedback high enough"
+3. **Add guidance**: "Video walkthroughs are gold—always rate them 4-5"
+4. **Deploy** (just edit the prompt file)
+5. **Repeat**
+
+No code changes. No recompilation. Just prose.
+</iteration>
+
+<checklist>
+## System Prompt Checklist
+
+- [ ] Clear identity statement
+- [ ] Core behaviors that always apply
+- [ ] Features as separate sections
+- [ ] Judgment criteria instead of rigid rules
+- [ ] Examples for ambiguous cases
+- [ ] Explicit boundaries (what NOT to do)
+- [ ] Tone guidance
+- [ ] Tool usage guidance (when to use each)
+- [ ] Memory/context handling
+</checklist>

package/plugins/compound-engineering/skills/andrew-kane-gem-writer/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: andrew-kane-gem-writer
+description: This skill should be used when writing Ruby gems following Andrew Kane's proven patterns and philosophy. It applies when creating new Ruby gems, refactoring existing gems, designing gem APIs, or when clean, minimal, production-ready Ruby library code is needed. Triggers on requests like "create a gem", "write a Ruby library", "design a gem API", or mentions of Andrew Kane's style.
+---
+
+# Andrew Kane Gem Writer
+
+Write Ruby gems following Andrew Kane's battle-tested patterns from 100+ gems with 374M+ downloads (Searchkick, PgHero, Chartkick, Strong Migrations, Lockbox, Ahoy, Blazer, Groupdate, Neighbor, Blind Index).
+
+## Core Philosophy
+
+**Simplicity over cleverness.** Zero or minimal dependencies. Explicit code over metaprogramming. Rails integration without Rails coupling. Every pattern serves production use cases.
+
+## Entry Point Structure
+
+Every gem follows this exact pattern in `lib/gemname.rb`:
+
+```ruby
+# 1. Dependencies (stdlib preferred)
+require "forwardable"
+
+# 2. Internal modules
+require_relative "gemname/model"
+require_relative "gemname/version"
+
+# 3. Conditional Rails (CRITICAL - never require Rails directly)
+require_relative "gemname/railtie" if defined?(Rails)
+
+# 4. Module with config and errors
+module GemName
+  class Error < StandardError; end
+  class InvalidConfigError < Error; end
+
+  class << self
+    attr_accessor :timeout, :logger
+    attr_writer :client
+  end
+
+  self.timeout = 10  # Defaults set immediately
+end
+```
+
+## Class Macro DSL Pattern
+
+The signature Kane pattern—single method call configures everything:
+
+```ruby
+# Usage
+class Product < ApplicationRecord
+  searchkick word_start: [:name]
+end
+
+# Implementation
+module GemName
+  module Model
+    def gemname(**options)
+      unknown = options.keys - KNOWN_KEYWORDS
+      raise ArgumentError, "unknown keywords: #{unknown.join(", ")}" if unknown.any?
+
+      mod = Module.new
+      mod.module_eval do
+        define_method :some_method do
+          # implementation
+        end unless method_defined?(:some_method)
+      end
+      include mod
+
+      class_eval do
+        cattr_reader :gemname_options, instance_reader: false
+        class_variable_set :@@gemname_options, options.dup
+      end
+    end
+  end
+end
+```
+
+## Rails Integration
+
+**Always use `ActiveSupport.on_load`—never require Rails gems directly:**
+
+```ruby
+# WRONG
+require "active_record"
+ActiveRecord::Base.include(MyGem::Model)
+
+# CORRECT
+ActiveSupport.on_load(:active_record) do
+  extend GemName::Model
+end
+
+# Use prepend for behavior modification
+ActiveSupport.on_load(:active_record) do
+  ActiveRecord::Migration.prepend(GemName::Migration)
+end
+```
+
+## Configuration Pattern
+
+Use `class << self` with `attr_accessor`, not Configuration objects:
+
+```ruby
+module GemName
+  class << self
+    attr_accessor :timeout, :logger
+    attr_writer :master_key
+  end
+
+  def self.master_key
+    @master_key ||= ENV["GEMNAME_MASTER_KEY"]
+  end
+
+  self.timeout = 10
+  self.logger = nil
+end
+```
+
+## Error Handling
+
+Simple hierarchy with informative messages:
+
+```ruby
+module GemName
+  class Error < StandardError; end
+  class ConfigError < Error; end
+  class ValidationError < Error; end
+end
+
+# Validate early with ArgumentError
+def initialize(key:)
+  raise ArgumentError, "Key must be 32 bytes" unless key&.bytesize == 32
+end
+```
+
+## Testing (Minitest Only)
+
+```ruby
+# test/test_helper.rb
+require "bundler/setup"
+Bundler.require(:default)
+require "minitest/autorun"
+require "minitest/pride"
+
+# test/model_test.rb
+class ModelTest < Minitest::Test
+  def test_basic_functionality
+    assert_equal expected, actual
+  end
+end
+```
+
+## Gemspec Pattern
+
+Zero runtime dependencies when possible:
+
+```ruby
+Gem::Specification.new do |spec|
+  spec.name = "gemname"
+  spec.version = GemName::VERSION
+  spec.required_ruby_version = ">= 3.1"
+  spec.files = Dir["*.{md,txt}", "{lib}/**/*"]
+  spec.require_path = "lib"
+  # NO add_dependency lines - dev deps go in Gemfile
+end
+```
+
+## Anti-Patterns to Avoid
+
+- `method_missing` (use `define_method` instead)
+- Configuration objects (use class accessors)
+- `@@class_variables` (use `class << self`)
+- Requiring Rails gems directly
+- Many runtime dependencies
+- Committing Gemfile.lock in gems
+- RSpec (use Minitest)
+- Heavy DSLs (prefer explicit Ruby)
+
+## Reference Files
+
+For deeper patterns, see:
+- **[references/module-organization.md](references/module-organization.md)** - Directory layouts, method decomposition
+- **[references/rails-integration.md](references/rails-integration.md)** - Railtie, Engine, on_load patterns
+- **[references/database-adapters.md](references/database-adapters.md)** - Multi-database support patterns
+- **[references/testing-patterns.md](references/testing-patterns.md)** - Multi-version testing, CI setup
+- **[references/resources.md](references/resources.md)** - Links to Kane's repos and articles

package/plugins/compound-engineering/skills/andrew-kane-gem-writer/references/database-adapters.md

@@ -0,0 +1,231 @@
+# Database Adapter Patterns
+
+## Abstract Base Class Pattern
+
+```ruby
+# lib/strong_migrations/adapters/abstract_adapter.rb
+module StrongMigrations
+  module Adapters
+    class AbstractAdapter
+      def initialize(checker)
+        @checker = checker
+      end
+
+      def min_version
+        nil
+      end
+
+      def set_statement_timeout(timeout)
+        # no-op by default
+      end
+
+      def check_lock_timeout
+        # no-op by default
+      end
+
+      private
+
+      def connection
+        @checker.send(:connection)
+      end
+
+      def quote(value)
+        connection.quote(value)
+      end
+    end
+  end
+end
+```
+
+## PostgreSQL Adapter
+
+```ruby
+# lib/strong_migrations/adapters/postgresql_adapter.rb
+module StrongMigrations
+  module Adapters
+    class PostgreSQLAdapter < AbstractAdapter
+      def min_version
+        "12"
+      end
+
+      def set_statement_timeout(timeout)
+        select_all("SET statement_timeout = #{timeout.to_i * 1000}")
+      end
+
+      def set_lock_timeout(timeout)
+        select_all("SET lock_timeout = #{timeout.to_i * 1000}")
+      end
+
+      def check_lock_timeout
+        lock_timeout = connection.select_value("SHOW lock_timeout")
+        lock_timeout_sec = timeout_to_sec(lock_timeout)
+        # validation logic
+      end
+
+      private
+
+      def select_all(sql)
+        connection.select_all(sql)
+      end
+
+      def timeout_to_sec(timeout)
+        units = {"us" => 1e-6, "ms" => 1e-3, "s" => 1, "min" => 60}
+        timeout.to_f * (units[timeout.gsub(/\d+/, "")] || 1e-3)
+      end
+    end
+  end
+end
+```
+
+## MySQL Adapter
+
+```ruby
+# lib/strong_migrations/adapters/mysql_adapter.rb
+module StrongMigrations
+  module Adapters
+    class MySQLAdapter < AbstractAdapter
+      def min_version
+        "8.0"
+      end
+
+      def set_statement_timeout(timeout)
+        select_all("SET max_execution_time = #{timeout.to_i * 1000}")
+      end
+
+      def check_lock_timeout
+        lock_timeout = connection.select_value("SELECT @@lock_wait_timeout")
+        # validation logic
+      end
+    end
+  end
+end
+```
+
+## MariaDB Adapter (MySQL variant)
+
+```ruby
+# lib/strong_migrations/adapters/mariadb_adapter.rb
+module StrongMigrations
+  module Adapters
+    class MariaDBAdapter < MySQLAdapter
+      def min_version
+        "10.5"
+      end
+
+      # Override MySQL-specific behavior
+      def set_statement_timeout(timeout)
+        select_all("SET max_statement_time = #{timeout.to_i}")
+      end
+    end
+  end
+end
+```
+
+## Adapter Detection Pattern
+
+Use regex matching on adapter name:
+
+```ruby
+def adapter
+  @adapter ||= case connection.adapter_name
+    when /postg/i
+      Adapters::PostgreSQLAdapter.new(self)
+    when /mysql|trilogy/i
+      if connection.try(:mariadb?)
+        Adapters::MariaDBAdapter.new(self)
+      else
+        Adapters::MySQLAdapter.new(self)
+      end
+    when /sqlite/i
+      Adapters::SQLiteAdapter.new(self)
+    else
+      Adapters::AbstractAdapter.new(self)
+    end
+end
+```
+
+## Multi-Database Support (PgHero pattern)
+
+```ruby
+module PgHero
+  class << self
+    attr_accessor :databases
+  end
+
+  self.databases = {}
+
+  def self.primary_database
+    databases.values.first
+  end
+
+  def self.capture_query_stats(database: nil)
+    db = database ? databases[database] : primary_database
+    db.capture_query_stats
+  end
+
+  class Database
+    attr_reader :id, :config
+
+    def initialize(id, config)
+      @id = id
+      @config = config
+    end
+
+    def connection_model
+      @connection_model ||= begin
+        Class.new(ActiveRecord::Base) do
+          self.abstract_class = true
+        end.tap do |model|
+          model.establish_connection(config)
+        end
+      end
+    end
+
+    def connection
+      connection_model.connection
+    end
+  end
+end
+```
+
+## Connection Switching
+
+```ruby
+def with_connection(database_name)
+  db = databases[database_name.to_s]
+  raise Error, "Unknown database: #{database_name}" unless db
+
+  yield db.connection
+end
+
+# Usage
+PgHero.with_connection(:replica) do |conn|
+  conn.execute("SELECT * FROM users")
+end
+```
+
+## SQL Dialect Handling
+
+```ruby
+def quote_column(column)
+  case adapter_name
+  when /postg/i
+    %("#{column}")
+  when /mysql/i
+    "`#{column}`"
+  else
+    column
+  end
+end
+
+def boolean_value(value)
+  case adapter_name
+  when /postg/i
+    value ? "true" : "false"
+  when /mysql/i
+    value ? "1" : "0"
+  else
+    value.to_s
+  end
+end
+```