[OSCER-309] Explore generator for reference files as agent rules for downstream projects (#310)

## Summary

Closes #309 — Explore generator for reference files as agent rules for
downstream projects

Implements `strata:rules` Rails generator that produces path-scoped
agent rule files for the Application Form SDK component. Generator reads
SDK source files and renders ERB templates into target agent's rules
directory (`.agents/rules/strata-sdk/`, `.claude/rules/strata-sdk/`,
etc.). Rules contain embedded source code excerpts that stay current on
re-generation.

## Changes

- Add SourceExcerptHelper module for reading SDK source files and
extracting documentation sections
- Add RulesGenerator skeleton with git root detection and --agent flag
support
- Add application_form root rule template with overview + quick
reference
- Add 3 application_form sub-templates: core-class, attributes,
determinable with full source embeds
- Add comprehensive RSpec test suite (39 examples, all passing)
- Update docs/generators.md with strata:rules documentation
- Update rule paths with **/app prefix for nested app directories
(monorepo support)

## Test plan

Manually tested rule generation and loading in:
- Antigravity
- Cursor
- Claude

Rules load correctly and are scoped to relevant file paths.

Example of how my agent in Antigravity used these files:

<img width="1157" height="673" alt="Screenshot 2026-04-17 at 1 53 42 PM"
src="https://github.com/user-attachments/assets/1a1856f8-2ea0-47cf-ad0c-d525f47de4ed"
/>
<img width="871" height="1313" alt="Screenshot 2026-04-17 at 2 19 40 PM"
src="https://github.com/user-attachments/assets/758bf8b8-540d-404e-87db-eccc90c255b1"
/>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: baonguyenNava

docs/generators.md

@@ -85,6 +85,21 @@ Creates a standard set of files required for implementing a staff dashboard in a
 bin/rails generate strata:staff
 ```
 
+### strata:rules
+
+Generates path-scoped agent rule files for Strata SDK features. Rules embed current SDK source code so re-running the generator updates rules to match the installed version. [See full usage guide](../lib/generators/strata/rules/USAGE)
+
+```bash
+bin/rails generate strata:rules FEATURE_NAME [--agent AGENT]
+```
+
+Supported features: `application_form`, `all`
+
+Output directory (defaults to `.agents/rules/strata-sdk/`):
+- `--agent claude` → `.claude/rules/strata-sdk/`
+- `--agent cursor` → `.cursor/rules/strata-sdk/`
+- `--agent copilot` → `.copilot/rules/strata-sdk/`
+
 ## Generator Dependencies
 
 - When generating a case, the generator will check for the existence of associated business process and application form classes

lib/generators/strata/rules/USAGE

@@ -0,0 +1,23 @@
+Description:
+    Generates path-scoped agent rule files for Strata SDK features.
+    Rules embed current SDK source code excerpts so re-running the
+    generator updates rules to match the installed SDK version.
+
+    Output goes to .agents/rules/strata-sdk/ by default.
+    Use --agent to target a specific agent's rules directory.
+
+Examples:
+    bin/rails generate strata:rules application_form
+    bin/rails generate strata:rules application_form --agent claude
+    bin/rails generate strata:rules application_form --agent cursor
+    bin/rails generate strata:rules all
+
+Supported features:
+    application_form    Application form model, attributes, and determinable
+    all                 Generate rules for all supported features
+
+Agent directories:
+    --agent claude      .claude/rules/strata-sdk/
+    --agent cursor      .cursor/rules/strata-sdk/
+    --agent copilot     .copilot/rules/strata-sdk/
+    (default)           .agents/rules/strata-sdk/

lib/generators/strata/rules/rules_generator.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "erb"
+require_relative "source_excerpt_helper"
+
+module Strata
+  module Generators
+    # Generates path-scoped agent rule files for Strata SDK features.
+    # Rules embed current SDK source code so re-running the generator
+    # updates rules to match the installed SDK version.
+    class RulesGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+      include SourceExcerptHelper
+
+      SUPPORTED_FEATURES = %w[application_form].freeze
+
+      # Manifest of all SDK source files referenced by templates.
+      # Specs validate these paths still exist, catching drift when
+      # SDK files are renamed or removed.
+      SOURCE_REFERENCES = {
+        "application_form" => {
+          files: %w[
+            app/models/strata/application_form.rb
+            app/lib/strata/attributes.rb
+            app/lib/strata/attributes/address_attribute.rb
+            app/lib/strata/attributes/name_attribute.rb
+            app/lib/strata/attributes/memorable_date_attribute.rb
+            app/models/concerns/strata/determinable.rb
+            app/views/strata/application_forms/index.html.erb
+            app/views/strata/application_forms/show.html.erb
+            app/views/strata/shared/_form_buttons.html.erb
+            app/views/strata/shared/_exit_link.html.erb
+            app/views/strata/shared/_breadcrumbs.html.erb
+            lib/generators/strata/application_form_views/templates/layout.html.erb.tt
+            lib/generators/strata/application_form_views/templates/edit_page.html.erb.tt
+            docs/intake-application-forms.md
+            docs/multi-page-form-flows.md
+          ]
+        }
+      }.freeze
+
+      AGENT_DIRS = {
+        "claude" => ".claude/rules",
+        "cursor" => ".cursor/rules",
+        "copilot" => ".copilot/rules"
+      }.freeze
+
+      DEFAULT_RULES_DIR = ".agents/rules"
+
+      desc "Generates path-scoped agent rules for Strata SDK features"
+
+      class_option :agent, type: :string,
+        desc: "Target agent (claude, cursor, copilot). Default: writes to .agents/rules/"
+      class_option :force, type: :boolean, default: true,
+        desc: "Overwrite existing rule files"
+
+      def validate_feature_name
+        return if name == "all"
+
+        unless SUPPORTED_FEATURES.include?(name.underscore)
+          raise Thor::Error, "Unknown feature '#{name}'. Supported: #{SUPPORTED_FEATURES.join(', ')}, all"
+        end
+      end
+
+      def generate_rules
+        features = name == "all" ? SUPPORTED_FEATURES : [ name.underscore ]
+        features.each do |feature|
+          # Root rule file
+          render_erb_template(
+            "#{feature}.md.erb",
+            File.join(output_dir, "strata-sdk", "strata-#{feature.dasherize}.md")
+          )
+
+          # Sub-rule files from feature subdirectory
+          sub_template_dir = File.join(self.class.source_root, feature)
+          next unless File.directory?(sub_template_dir)
+
+          Dir.glob("#{sub_template_dir}/*.md.erb").sort.each do |sub_template_path|
+            sub_name = File.basename(sub_template_path, ".md.erb")
+            render_erb_template(
+              File.join(feature, "#{sub_name}.md.erb"),
+              File.join(output_dir, "strata-sdk", "strata-#{feature.dasherize}", "#{sub_name}.md")
+            )
+          end
+        end
+      end
+
+      private
+
+      # Walk up from destination_root to find the git root (.git directory).
+      # Falls back to destination_root if no .git is found (e.g., in tests).
+      def git_root
+        dir = Pathname.new(destination_root).expand_path
+        loop do
+          return dir if (dir + ".git").exist?
+          parent = dir.parent
+          return Pathname.new(destination_root).expand_path if parent == dir
+          dir = parent
+        end
+      end
+
+      def output_dir
+        agent_subdir = AGENT_DIRS.fetch(options[:agent]&.downcase, DEFAULT_RULES_DIR)
+        git_root.join(agent_subdir).to_s
+      end
+
+      def render_erb_template(template_relative_path, destination)
+        source_path = File.join(self.class.source_root, template_relative_path)
+        erb_content = File.read(source_path, encoding: "UTF-8")
+        rendered = ERB.new(erb_content, trim_mode: "-").result(binding)
+        create_file destination, rendered
+      end
+    end
+  end
+end

lib/generators/strata/rules/source_excerpt_helper.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Strata
+  module Generators
+    # Helper methods for reading SDK source files and documentation sections.
+    # Included in RulesGenerator to make helpers available in ERB template bindings.
+    module SourceExcerptHelper
+      def sdk_root
+        Strata::Engine.root
+      end
+
+      # Reads a file relative to the SDK root. Returns content as a string.
+      # Raises if the file does not exist.
+      def read_sdk_file(relative_path)
+        full_path = sdk_root.join(relative_path)
+        raise "SDK file not found: #{relative_path} (looked at #{full_path})" unless File.exist?(full_path)
+        File.read(full_path, encoding: "UTF-8").strip
+      end
+
+      # Extracts a markdown section by heading from a doc file in docs/.
+      # Returns everything between the matched heading and the next heading
+      # of the same or higher level. Returns empty string if heading not found.
+      def excerpt_doc_section(doc_filename, section_heading)
+        doc_path = sdk_root.join("docs", doc_filename)
+        raise "Doc file not found: #{doc_filename} (looked at #{doc_path})" unless File.exist?(doc_path)
+
+        content = File.read(doc_path, encoding: "UTF-8")
+        lines = content.lines
+
+        heading_idx = lines.index { |l| l.strip.match?(/^#+\s+#{Regexp.escape(section_heading)}\s*$/) }
+        return "" unless heading_idx
+
+        level = lines[heading_idx].match(/^(#+)/)[1].length
+
+        body_lines = []
+        lines[(heading_idx + 1)..].each do |line|
+          if line.match?(/^(#+)\s/)
+            line_level = line.match(/^(#+)/)[1].length
+            break if line_level <= level
+          end
+          body_lines << line
+        end
+
+        body_lines.join.strip
+      end
+    end
+  end
+end

lib/generators/strata/rules/templates/application_form.md.erb

@@ -0,0 +1,33 @@
+---
+paths:
+  - "**/app/models/**/*application_form*.rb"
+  - "**/app/controllers/**/*application_forms*.rb"
+---
+
+# Strata SDK: Application Forms
+
+Rules for building application forms with the Strata SDK. Application forms implement intake processes for government digital services.
+
+## What is an Application Form?
+
+<%= excerpt_doc_section("intake-application-forms.md", "What is an Application Form?") %>
+
+## Build Recipe
+
+Building a new application form = 6 steps: generate model, test model, generate controller, test controller, build views, test views. Full recipe with commands + test templates:
+
+→ **`strata-application-form/recipe.md`** (auto-loads when editing any application form file)
+
+
+
+## Detailed Reference (Sub-rules)
+
+For implementation details, these sub-rules load automatically when working on application form files:
+
+| File | Contents |
+|------|----------|
+| `strata-sdk/strata-application-form/recipe.md` | Build recipe: 6-step gen→test workflow with commands and test templates |
+| `strata-sdk/strata-application-form/core-class.md` | Full ApplicationForm source, event system, submission internals |
+| `strata-sdk/strata-application-form/attributes.md` | Strata::Attributes module source, column mappings, attribute type details |
+| `strata-sdk/strata-application-form/determinable.md` | Strata::Determinable source, recording determinations |
+| `strata-sdk/strata-application-form/views.md` | Generated question-page templates, shared partials, index/show views, required I18n keys |

lib/generators/strata/rules/templates/application_form/attributes.md.erb

@@ -0,0 +1,66 @@
+---
+paths:
+  - "**/app/models/**/*application_form*.rb"
+  - "**/app/models/**/*form*.rb"
+---
+
+# Strata SDK: Strata Attributes
+
+Full source and usage for the `Strata::Attributes` module and the `strata_attribute` DSL.
+
+## Attributes Module Source
+
+```ruby
+<%= read_sdk_file("app/lib/strata/attributes.rb") %>
+```
+
+## Column Mappings by Type
+
+| Attribute Type | Database Column(s) | Ruby Type |
+|---------------|-------------------|-----------|
+| `name` | `{attr}_first`, `{attr}_middle`, `{attr}_last`, `{attr}_suffix` | Hash → `Strata::Name` |
+| `address` | `{attr}_street_line_1`, `_street_line_2`, `_city`, `_state`, `_zip_code` | Hash → `Strata::Address` |
+| `memorable_date` | `{attr}_date` | Date (via hash: year/month/day) |
+| `money` | `{attr}` (integer, cents) | `Strata::Money` |
+| `tax_id` | `{attr}` (string) | String |
+| `array` | `{attr}` (jsonb) | Array of hashes |
+| `us_date` | `{attr}` (date) | Date |
+| `range` | `{attr}_min`, `{attr}_max` | Hash |
+| `year_month` | `{attr}_year`, `{attr}_month` | Hash (2 integers) |
+| `year_quarter` | `{attr}_year`, `{attr}_quarter` | Hash (2 integers) |
+
+## Address Attribute Source
+
+```ruby
+<%= read_sdk_file("app/lib/strata/attributes/address_attribute.rb") %>
+```
+
+## Name Attribute Source
+
+```ruby
+<%= read_sdk_file("app/lib/strata/attributes/name_attribute.rb") %>
+```
+
+## Memorable Date Attribute Source
+
+```ruby
+<%= read_sdk_file("app/lib/strata/attributes/memorable_date_attribute.rb") %>
+```
+
+## Declaration Pattern
+
+```ruby
+class MyForm < Strata::ApplicationForm
+  strata_attribute :applicant_name, :name        # 4 columns
+  strata_attribute :home_address, :address        # 5 columns
+  strata_attribute :birth_date, :memorable_date   # 1 column: birth_date_date
+  strata_attribute :salary, :money                # 1 column: salary (integer, cents)
+  strata_attribute :ssn, :tax_id                  # 1 column: ssn (string)
+end
+```
+
+## Migration Generation
+
+```bash
+bin/rails generate strata:migration AddFieldsToMyForm applicant_name:name salary:money
+```

lib/generators/strata/rules/templates/application_form/core-class.md.erb

@@ -0,0 +1,59 @@
+---
+paths:
+  - "**/app/models/**/*application_form*.rb"
+  - "**/app/controllers/**/*application_forms*.rb"
+---
+
+# Strata SDK: ApplicationForm — Core Class
+
+Full source and implementation details for `Strata::ApplicationForm`.
+
+## Source Code
+
+```ruby
+<%= read_sdk_file("app/models/strata/application_form.rb") %>
+```
+
+## Creating a Form Model
+
+1. **Generate:**
+   ```bash
+   bin/rails generate strata:application_form PassportApplicationForm \
+     name:name birth_date:memorable_date ssn:tax_id residential_address:address
+   ```
+
+2. **Run migrations:**
+   ```bash
+   bin/rails db:migrate
+   ```
+
+3. **Add submission validations** (use `:submit` context):
+   ```ruby
+   class PassportApplicationForm < Strata::ApplicationForm
+     strata_attribute :applicant_name, :name
+     strata_attribute :birth_date, :memorable_date
+     strata_attribute :ssn, :tax_id
+     strata_attribute :residential_address, :address
+
+     validates :applicant_name_first, presence: true, on: :submit
+     validates :ssn, presence: true, on: :submit
+   end
+   ```
+
+## Events
+
+| Event | When | Payload |
+|-------|------|---------|
+| `{ClassName}Created` | After record created | `{ application_form_id: id }` |
+| `{ClassName}Submitted` | After `submit_application` succeeds | `{ application_form_id: id, submitted_at: timestamp }` |
+
+These events integrate with `Strata::BusinessProcess` via `start_on_application_form_created` and transition handlers.
+
+## Submission Internals
+
+`submit_application` does the following in order:
+1. Validates with `:submit` context — returns `false` if invalid
+2. Runs `:submit` callbacks (`before_submit`, `after_submit`)
+3. Sets `status` to `:submitted` and `submitted_at` to `Time.current`
+4. Saves the record
+5. Publishes `{ClassName}Submitted` event