@fro.bot/systematic 1.18.7 → 1.19.0

package/commands/workflows/plan.md

@@ -178,6 +178,7 @@ Select how comprehensive you want the issue to be, simpler is mostly better.
 ---
 title: [Issue Title]
 type: [feat|fix|refactor]
+status: active
 date: YYYY-MM-DD
 ---
 
@@ -230,6 +231,7 @@ end
 ---
 title: [Issue Title]
 type: [feat|fix|refactor]
+status: active
 date: YYYY-MM-DD
 ---
 
@@ -253,6 +255,14 @@ date: YYYY-MM-DD
 - Performance implications
 - Security considerations
 
+## System-Wide Impact
+
+- **Interaction graph**: [What callbacks/middleware/observers fire when this runs?]
+- **Error propagation**: [How do errors flow across layers? Do retry strategies align?]
+- **State lifecycle risks**: [Can partial failure leave orphaned/inconsistent state?]
+- **API surface parity**: [What other interfaces expose similar functionality and need the same change?]
+- **Integration test scenarios**: [Cross-layer scenarios that unit tests won't catch]
+
 ## Acceptance Criteria
 
 - [ ] Detailed requirement 1
@@ -294,6 +304,7 @@ date: YYYY-MM-DD
 ---
 title: [Issue Title]
 type: [feat|fix|refactor]
+status: active
 date: YYYY-MM-DD
 ---
 
@@ -341,6 +352,28 @@ date: YYYY-MM-DD
 
 [Other solutions evaluated and why rejected]
 
+## System-Wide Impact
+
+### Interaction Graph
+
+[Map the chain reaction: what callbacks, middleware, observers, and event handlers fire when this code runs? Trace at least two levels deep. Document: "Action X triggers Y, which calls Z, which persists W."]
+
+### Error & Failure Propagation
+
+[Trace errors from lowest layer up. List specific error classes and where they're handled. Identify retry conflicts, unhandled error types, and silent failure swallowing.]
+
+### State Lifecycle Risks
+
+[Walk through each step that persists state. Can partial failure orphan rows, duplicate records, or leave caches stale? Document cleanup mechanisms or their absence.]
+
+### API Surface Parity
+
+[List all interfaces (classes, DSLs, endpoints) that expose equivalent functionality. Note which need updating and which share the code path.]
+
+### Integration Test Scenarios
+
+[3-5 cross-layer test scenarios that unit tests with mocks would never catch. Include expected behavior for each.]
+
 ## Acceptance Criteria
 
 ### Functional Requirements
@@ -472,6 +505,20 @@ end
 - [ ] Add names of files in pseudo code examples and todo lists
 - [ ] Add an ERD mermaid diagram if applicable for new model changes
 
+## Write Plan File
+
+**REQUIRED: Write the plan file to disk before presenting any options.**
+
+```bash
+mkdir -p docs/plans/
+```
+
+Use the write tool to save the complete plan to `docs/plans/YYYY-MM-DD-<type>-<descriptive-name>-plan.md`. This step is mandatory and cannot be skipped — even when running as part of LFG/SLFG or other automated pipelines.
+
+Confirm: "Plan written to docs/plans/[filename]"
+
+**Pipeline mode:** If invoked from an automated workflow (LFG, SLFG, or any `disable-model-invocation` context), skip all question calls. Make decisions automatically and proceed to writing the plan without interactive prompts.
+
 ## Output Format
 
 **Filename:** Use the date and kebab-case filename from Step 2 Title & Categorization.
@@ -501,7 +548,7 @@ After writing the plan file, use the **question tool** to present these options:
 3. **Run `/technical_review`** - Technical feedback from code-focused reviewers (DHH, Kieran, Simplicity)
 4. **Review and refine** - Improve the document through structured self-review
 5. **Start `/workflows:work`** - Begin implementing this plan locally
-6. **Create Issue** - Create issue in project tracker (GitHub/Linear)
+7. **Create Issue** - Create issue in project tracker (GitHub/Linear)
 
 Based on selection:
 - **Open plan in editor** → Run `open docs/plans/<plan_filename>.md` to open the file in the user's default editor
@@ -509,6 +556,7 @@ Based on selection:
 - **`/technical_review`** → Call the /technical_review command with the plan file path
 - **Review and refine** → Load `document-review` skill.
 - **`/workflows:work`** → Call the /workflows:work command with the plan file path
+- **`/workflows:work` on remote** → Run `/workflows:work docs/plans/<plan_filename>.md &` to start work in background
 - **Create Issue** → See "Issue Creation" section below
 - **Other** (automatically provided) → Accept free text for rework or specific changes
 

package/commands/workflows/review.md

@@ -31,7 +31,7 @@ argument-hint: '[PR number, GitHub URL, branch name, or latest]'
 First, I need to determine the review target type and set up the code for analysis.
 </thinking>
 
-#### Immediate Actions
+#### Immediate Actions:
 
 <task_list>
 
@@ -59,45 +59,48 @@ The following paths are systematic pipeline artifacts and must never be flagged
 If a review agent flags any file in these directories for cleanup or removal, discard that finding during synthesis. Do not create a todo for it.
 </protected_artifacts>
 
-#### Parallel Agents to review the PR
+#### Load Review Agents
+
+Read `systematic.local.md` in the project root. If found, use `review_agents` from YAML frontmatter. If the markdown body contains review context, pass it to each agent as additional instructions.
+
+If no settings file exists, invoke the `setup` skill to create one. Then read the newly created file and continue.
+
+#### Parallel Agents to review the PR:
 
 <parallel_tasks>
 
-Run ALL or most of these agents at the same time:
+Run all configured review agents in parallel using task tool. For each agent in the `review_agents` list:
+
+```
+Task {agent-name}(PR content + review context from settings body)
+```
 
-1. task kieran-rails-reviewer(PR content) - If Rails project
-2. task dhh-rails-reviewer(PR title) - If Rails project
-3. task kieran-typescript-reviewer(PR content) - If TypeScript project
-4. task git-history-analyzer(PR content)
-5. task pattern-recognition-specialist(PR content)
-6. task architecture-strategist(PR content)
-7. task security-sentinel(PR content)
-8. task performance-oracle(PR content)
-9. task data-integrity-guardian(PR content)
-10. task agent-native-reviewer(PR content) - Verify new features are agent-accessible
-11. task code-simplicity-reviewer(PR content)
+Additionally, always run these regardless of settings:
+- task agent-native-reviewer(PR content) - Verify new features are agent-accessible
+- task learnings-researcher(PR content) - Search docs/solutions/ for past issues related to this PR's modules and patterns
 
 </parallel_tasks>
 
-#### Conditional Agents (Run if applicable)
+#### Conditional Agents (Run if applicable):
 
 <conditional_agents>
 
 These agents are run ONLY when the PR matches specific criteria. Check the PR files list to determine if they apply:
 
-**If PR contains database migrations (db/migrate/*.rb files) or data backfills:**
+**MIGRATIONS: If PR contains database migrations, schema.rb, or data backfills:**
 
-14. task data-migration-expert(PR content) - Validates ID mappings match production, checks for swapped values, verifies rollback safety
-15. task deployment-verification-agent(PR content) - Creates Go/No-Go deployment checklist with SQL verification queries
+- task schema-drift-detector(PR content) - Detects unrelated schema.rb changes by cross-referencing against included migrations (run FIRST)
+- task data-migration-expert(PR content) - Validates ID mappings match production, checks for swapped values, verifies rollback safety
+- task deployment-verification-agent(PR content) - Creates Go/No-Go deployment checklist with SQL verification queries
 
-**When to run migration agents:**
-- PR includes files matching `db/migrate/*.rb`
+**When to run:**
+- PR includes files matching `db/migrate/*.rb` or `db/schema.rb`
 - PR modifies columns that store IDs, enums, or mappings
 - PR includes data backfill scripts or rake tasks
-- PR changes how data is read/written (e.g., changing from FK to string column)
 - PR title/body mentions: migration, backfill, data transformation, ID mapping
 
 **What these agents check:**
+- `schema-drift-detector`: Cross-references schema.rb changes against PR migrations to catch unrelated columns/indexes from local database state
 - `data-migration-expert`: Verifies hard-coded mappings match production reality (prevents swapped IDs), checks for orphaned associations, validates dual-write patterns
 - `deployment-verification-agent`: Produces executable pre/post-deploy checklists with SQL queries, rollback procedures, and monitoring plans
 
@@ -216,6 +219,7 @@ Remove duplicates, prioritize by severity and impact.
 <synthesis_tasks>
 
 - [ ] Collect findings from all parallel agents
+- [ ] Surface learnings-researcher results: if past solutions are relevant, flag them as "Known Pattern" with links to docs/solutions/ files
 - [ ] Discard any findings that recommend deleting or gitignoring files in `docs/plans/` or `docs/solutions/` (see Protected Artifacts above)
 - [ ] Categorize by type: security, performance, architecture, quality, etc.
 - [ ] Assign severity levels: 🔴 CRITICAL (P1), 🟡 IMPORTANT (P2), 🔵 NICE-TO-HAVE (P3)
@@ -410,7 +414,7 @@ After creating all todo files, present comprehensive summary:
    - Update Work Log as you work
    - Commit todos: `git add todos/ && git commit -m "refactor: add code review findings"`
 
-### Severity Breakdown
+### Severity Breakdown:
 
 **🔴 P1 (Critical - Blocks Merge):**
 
@@ -478,7 +482,7 @@ After presenting the Summary Report, offer appropriate testing based on project
 
 </offer_testing>
 
-#### If User Accepts Web Testing
+#### If User Accepts Web Testing:
 
 Spawn a subagent to run browser tests (preserves main context):
 
@@ -497,7 +501,7 @@ The subagent will:
 
 **Standalone:** `/test-browser [PR number]`
 
-#### If User Accepts iOS Testing
+#### If User Accepts iOS Testing:
 
 Spawn a subagent to run Xcode tests (preserves main context):
 

package/commands/workflows/work.md

@@ -87,17 +87,32 @@ This command takes a work document (plan, specification, or todo file) and execu
 
    ```
    while (tasks remain):
-      - Mark task as in_progress in todowrite
+     - Mark task as in_progress in todowrite
      - Read any referenced files from the plan
      - Look for similar patterns in codebase
      - Implement following existing conventions
      - Write tests for new functionality
+     - Run System-Wide Test Check (see below)
      - Run tests after changes
-      - Mark task as completed in todowrite
+     - Mark task as completed in todowrite
      - Mark off the corresponding checkbox in the plan file ([ ] → [x])
      - Evaluate for incremental commit (see below)
    ```
 
+   **System-Wide Test Check** — Before marking a task done, pause and ask:
+
+   | Question | What to do |
+   |----------|------------|
+   | **What fires when this runs?** Callbacks, middleware, observers, event handlers — trace two levels out from your change. | Read the actual code (not docs) for callbacks on models you touch, middleware in the request chain, `after_*` hooks. |
+   | **Do my tests exercise the real chain?** If every dependency is mocked, the test proves your logic works *in isolation* — it says nothing about the interaction. | Write at least one integration test that uses real objects through the full callback/middleware chain. No mocks for the layers that interact. |
+   | **Can failure leave orphaned state?** If your code persists state (DB row, cache, file) before calling an external service, what happens when the service fails? Does retry create duplicates? | Trace the failure path with real objects. If state is created before the risky call, test that failure cleans up or that retry is idempotent. |
+   | **What other interfaces expose this?** Mixins, DSLs, alternative entry points (Agent vs Chat vs ChatMethods). | Grep for the method/behavior in related classes. If parity is needed, add it now — not as a follow-up. |
+   | **Do error strategies align across layers?** Retry middleware + application fallback + framework error handling — do they conflict or create double execution? | List the specific error classes at each layer. Verify your rescue list matches what the lower layer actually raises. |
+
+   **When to skip:** Leaf-node changes with no callbacks, no state persistence, no parallel interfaces. If the change is purely additive (new helper method, new view partial), the check takes 10 seconds and the answer is "nothing fires, skip."
+
+   **When this matters most:** Any change that touches models with callbacks, error handling with fallback/retry, or functionality exposed through multiple interfaces.
+
    **IMPORTANT**: Always update the original plan document by checking off completed items. Use the edit tool to change `- [ ]` to `- [x]` for each task you finish. This keeps the plan as a living document showing progress and ensures no checkboxes are left unchecked.
 
 2. **Incremental Commits**
@@ -134,7 +149,7 @@ This command takes a work document (plan, specification, or todo file) and execu
    - The plan should reference similar code - read those files first
    - Match naming conventions exactly
    - Reuse existing components where possible
-    - Follow project coding standards (see AGENTS.md)
+   - Follow project coding standards (see AGENTS.md)
    - When in doubt, grep for similar implementations
 
 4. **Test Continuously**
@@ -143,6 +158,7 @@ This command takes a work document (plan, specification, or todo file) and execu
    - Don't wait until the end to test
    - Fix failures immediately
    - Add new tests for new functionality
+   - **Unit tests with mocks prove logic in isolation. Integration tests with real objects prove the layers work together.** If your change touches callbacks, middleware, or error handling — you need both.
 
 5. **Figma Design Sync** (if applicable)
 
@@ -169,28 +185,15 @@ This command takes a work document (plan, specification, or todo file) and execu
    # Run full test suite (use project's test command)
    # Examples: bin/rails test, npm test, pytest, go test, etc.
 
-    # Run linting (per AGENTS.md)
+   # Run linting (per project conventions)
    # Use linting-agent before pushing to origin
    ```
 
 2. **Consider Reviewer Agents** (Optional)
 
-   Use for complex, risky, or large changes:
-
-   - **code-simplicity-reviewer**: Check for unnecessary complexity
-   - **kieran-rails-reviewer**: Verify Rails conventions (Rails projects)
-   - **performance-oracle**: Check for performance issues
-   - **security-sentinel**: Scan for security vulnerabilities
-   - **cora-test-reviewer**: Review test quality (Rails projects with comprehensive test coverage)
-
-   Run reviewers in parallel with task tool:
-
-   ```
-    task(code-simplicity-reviewer): "Review changes for simplicity"
-    task(kieran-rails-reviewer): "Check Rails conventions"
-   ```
+   Use for complex, risky, or large changes. Read agents from `systematic.local.md` frontmatter (`review_agents`). If no settings file, invoke the `setup` skill to create one.
 
-   Present findings to user and address critical issues.
+   Run configured agents in parallel with task tool. Present findings and address critical issues.
 
 3. **Final Validation**
    - All todowrite tasks marked completed
@@ -200,6 +203,16 @@ This command takes a work document (plan, specification, or todo file) and execu
    - Figma designs match (if applicable)
    - No console errors or warnings
 
+4. **Prepare Operational Validation Plan** (REQUIRED)
+   - Add a `## Post-Deploy Monitoring & Validation` section to the PR description for every change.
+   - Include concrete:
+     - Log queries/search terms
+     - Metrics or dashboards to watch
+     - Expected healthy signals
+     - Failure signals and rollback/mitigation trigger
+     - Validation window and owner
+   - If there is truly no production/runtime impact, still include the section with: `No additional operational monitoring required` and a one-line reason.
+
 ### Phase 4: Ship It
 
 1. **Create Commit**
@@ -215,9 +228,9 @@ This command takes a work document (plan, specification, or todo file) and execu
 
    Brief explanation if needed.
 
-    🤖 Generated with [OpenCode](https://opencode.ai)
+   🤖 Generated with [OpenCode](https://opencode.ai)
 
-    Co-Authored-By: OpenCode <noreply@opencode.ai>
+   Co-Authored-By: Claude <noreply@opencode.ai>
    EOF
    )"
    ```
@@ -269,6 +282,22 @@ This command takes a work document (plan, specification, or todo file) and execu
    - Tests added/modified
    - Manual testing performed
 
+   ## Post-Deploy Monitoring & Validation
+   - **What to monitor/search**
+     - Logs:
+     - Metrics/Dashboards:
+   - **Validation checks (queries/commands)**
+     - `command or query here`
+   - **Expected healthy behavior**
+     - Expected signal(s)
+   - **Failure signal(s) / rollback trigger**
+     - Trigger + immediate action
+   - **Validation window & owner**
+     - Window:
+     - Owner:
+   - **If no operational impact**
+     - `No additional operational monitoring required: <reason>`
+
    ## Before / After Screenshots
    | Before | After |
    |--------|-------|
@@ -279,12 +308,19 @@ This command takes a work document (plan, specification, or todo file) and execu
 
    ---
 
-    [![Systematic](https://img.shields.io/badge/Systematic-Engineered-6366f1)](https://github.com/marcusrbrown/systematic) 🤖 Generated with [OpenCode](https://opencode.ai)
+   [![Systematic](https://img.shields.io/badge/Compound-Engineered-6366f1)](https://github.com/marcusrbrown/systematic) 🤖 Generated with [OpenCode](https://opencode.ai)
    EOF
    )"
    ```
 
-4. **Notify User**
+4. **Update Plan Status**
+
+   If the input document has YAML frontmatter with a `status` field, update it to `completed`:
+   ```
+   status: active  →  status: completed
+   ```
+
+5. **Notify User**
    - Summarize what was completed
    - Link to PR
    - Note any follow-up work needed
@@ -294,8 +330,6 @@ This command takes a work document (plan, specification, or todo file) and execu
 
 ## Swarm Mode (Optional)
 
-> **Note:** Swarm mode coordination primitives (`Teammate` API — team creation, shutdown signals, cleanup) are not yet available in OpenCode. The concepts below are aspirational. For current parallel execution, use the `task` tool with multiple background subagents, or see the `dispatching-parallel-agents` skill.
-
 For complex plans with multiple independent workstreams, enable swarm mode for parallel execution with coordinated agents.
 
 ### When to Use Swarm Mode
@@ -409,6 +443,7 @@ Before creating PR, verify:
 - [ ] Figma designs match implementation (if applicable)
 - [ ] Before/after screenshots captured and uploaded (for UI changes)
 - [ ] Commit messages follow conventional format
+- [ ] PR description includes Post-Deploy Monitoring & Validation section (or explicit no-impact rationale)
 - [ ] PR description includes summary, testing notes, and screenshots
 - [ ] PR description includes Systematic badge
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fro.bot/systematic",
-  "version": "1.18.7",
+  "version": "1.19.0",
   "description": "Structured engineering workflows for OpenCode",
   "type": "module",
   "homepage": "https://fro.bot/systematic",

package/skills/andrew-kane-gem-writer/SKILL.md

@@ -0,0 +1,185 @@
+---
+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
+