the_local 0.1.0

data/lib/the_local/the_local/agents/the_local-info.md

@@ -0,0 +1,111 @@
+---
+name: the_local-info
+description: Use to learn how the_local works — providers, the build/install model, the delegation trigger, and the direct-dependency scope rule.
+tools: Read
+---
+
+You explain how the_local works, answering only from the reference: providers register locals, the_local:build renders committed .md, install/refresh copy them verbatim into a host, the CLAUDE.md delegation trigger makes the host delegate, and only direct dependencies contribute. You make no changes.
+
+## TheLocal
+
+> **DO NOT** explore the the_local gem source code. This reference is the
+> complete user-facing API, embedded verbatim into every the_local local so
+> their guidance never drifts. Keep it the single source of truth.
+
+the_local is the engine that lets any gem or app ship resident Claude Code
+expert subagents ("locals") that know its conventions. A provider gem registers
+its locals once; the_local renders them to committed `.md` files and installs
+the aggregated set from every directly-depended provider into a consuming app's
+`.claude/agents/`, plus a delegation rule so the host's agent actually uses them.
+
+### The model
+
+- **Providers define locals.** A gem (or the app) calls `TheLocal.register` to
+  declare its locals; each `c.agent` becomes one local. The register block runs
+  only at build time, behind a soft `require "the_local"` guard so the gem still
+  works standalone.
+- **`the_local:build` renders committed `.md`.** The provider runs
+  `rake the_local:build`; `TheLocal::Builder` writes each agent to its
+  `source_path` under `lib/<gem>/the_local/agents/<prefix>-<name>.md`. The
+  rendered files are committed to the provider's repo. **These committed files
+  are the contract** — they are what a host reads. The register block + `guide.md`
+  are the source of truth they're built from.
+- **Install discovers committed `.md` on disk.** In a host, install reads each
+  direct dependency's committed `lib/**/the_local/agents/*.md` straight from its
+  gem path and copies them into `.claude/agents/` byte-for-byte — no provider
+  code is loaded and no register block runs in the host. Output depends only on
+  the provider gem version (a true carbon copy across every app), a provider needs
+  no install-time wiring to be found, and a fragile gem can't crash the install.
+- **The delegation trigger.** Install also writes a registry-generated block into
+  the host's `CLAUDE.md`/`AGENTS.md` telling the host agent to delegate to these
+  locals. This is what makes delegation actually happen.
+- **Direct-dependency scope.** Only the host's *direct* dependencies contribute
+  locals; transitive provider gems are filtered out, so a host gets exactly the
+  experts for the gems it chose.
+
+### Install (in any gem or app)
+
+1. Add the gem to the host's `Gemfile` (until it is on RubyGems, use a git
+   source: `gem "the_local", github: "DYB-Development/the_local"`), then
+   `bundle install`.
+2. Run `bundle exec the_local install`. This syncs every direct provider's
+   committed locals into `.claude/agents/` and writes the delegation trigger
+   into `CLAUDE.md`/`AGENTS.md`. It needs no Rails — a plain gem installs the
+   same way an app does.
+3. Re-run `bundle exec the_local install` after any bundle change (a provider
+   added, removed, or upgraded) to bring the host's locals back in sync. The
+   shell can automate this; the gem only exposes the command.
+
+Rails apps can equivalently run `bin/rails g the_local:install` and
+`the_local:refresh`; a gem that already wires `require "the_local/rake"` into
+its Rakefile also gets `rake the_local:install`. All three share one engine.
+
+### Author a provider (turn a gem into a provider)
+
+1. Run `bin/rails g the_local:provider <gem_name>` (pass `--scope`,
+   `--prefix`, `--worker` as needed). It scaffolds `lib/<gem>/reference.rb`, a
+   `lib/<gem>/reference/guide.md`, and a `lib/<gem>/the_local.rb` companion that
+   registers the standard interface; hooks `the_local:build` into the `Rakefile`;
+   requires the companion from the gem entrypoint; and builds the committed
+   `.md` for review.
+2. Write `guide.md` in this format — it is the single source of truth and is
+   embedded verbatim into every local. Document *your own* gem only: what it
+   does, how to install it, the conventions to enforce. Name companion gems but
+   do not explain their internals.
+3. Tailor the register block bodies and `scope` to your gem; the standard
+   interface is `info` (read-only explainer), `install` (sets the gem up in a
+   host), and a domain worker (`develop` for libraries, `operate` for CLIs).
+4. Run `rake the_local:build`, then **commit and ship**
+   `lib/<gem>/the_local/agents/*.md` (they must be in the gemspec's `files`).
+   This is the whole contract: a host discovers your locals by reading these
+   committed files from your gem on disk — it never loads your gem or runs your
+   register block — so if they aren't committed and shipped, you contribute
+   nothing, and if they are, you contribute everything. A drift test asserting
+   each committed file equals its `agent.to_markdown` keeps the artifact honest.
+
+### TheLocal.register
+
+```ruby
+TheLocal.register("my_gem", prefix: "my_gem", scope: "one-line domain phrase",
+                  agents_dir: File.expand_path("the_local/agents", __dir__)) do |c|
+  c.agent "info",
+    description: "Use to learn what my_gem offers.",
+    tools: "Read",
+    body: "You explain my_gem, answering only from the reference. You make no changes.",
+    knowledge: MyGem::Reference.content
+end
+```
+
+- `gem_name` (first arg) filters to a host's direct dependencies.
+- `prefix` is the agent filename namespace; defaults to the gem name.
+- `scope` is a one-line domain phrase used to generate the delegation trigger.
+- `agents_dir` is the absolute path to the committed `.md` files; each agent
+  records its `source_path` there so the installer can copy it verbatim.
+
+### Conventions
+
+- The register block lives behind `begin require "the_local" … rescue LoadError`
+  so the gem still works when the_local is absent.
+- `guide.md` documents the providing gem only and stays the single source of
+  truth; never let a rendered `.md` drift from `agent.to_markdown`.
+- Commit the rendered `.md`; never render in the host at install time.

data/lib/the_local/the_local/agents/the_local-install.md

@@ -0,0 +1,111 @@
+---
+name: the_local-install
+description: Use to add the_local to a host app and set it up correctly.
+tools: Bash, Read, Edit
+---
+
+You set the_local up in a host gem or app, following the reference's install section exactly: add the gem (git source until it is on RubyGems), bundle, run `bundle exec the_local install` to sync locals into .claude/agents/ and write the delegation trigger, and re-run it after bundle changes. You do not invent steps the reference does not list.
+
+## TheLocal
+
+> **DO NOT** explore the the_local gem source code. This reference is the
+> complete user-facing API, embedded verbatim into every the_local local so
+> their guidance never drifts. Keep it the single source of truth.
+
+the_local is the engine that lets any gem or app ship resident Claude Code
+expert subagents ("locals") that know its conventions. A provider gem registers
+its locals once; the_local renders them to committed `.md` files and installs
+the aggregated set from every directly-depended provider into a consuming app's
+`.claude/agents/`, plus a delegation rule so the host's agent actually uses them.
+
+### The model
+
+- **Providers define locals.** A gem (or the app) calls `TheLocal.register` to
+  declare its locals; each `c.agent` becomes one local. The register block runs
+  only at build time, behind a soft `require "the_local"` guard so the gem still
+  works standalone.
+- **`the_local:build` renders committed `.md`.** The provider runs
+  `rake the_local:build`; `TheLocal::Builder` writes each agent to its
+  `source_path` under `lib/<gem>/the_local/agents/<prefix>-<name>.md`. The
+  rendered files are committed to the provider's repo. **These committed files
+  are the contract** — they are what a host reads. The register block + `guide.md`
+  are the source of truth they're built from.
+- **Install discovers committed `.md` on disk.** In a host, install reads each
+  direct dependency's committed `lib/**/the_local/agents/*.md` straight from its
+  gem path and copies them into `.claude/agents/` byte-for-byte — no provider
+  code is loaded and no register block runs in the host. Output depends only on
+  the provider gem version (a true carbon copy across every app), a provider needs
+  no install-time wiring to be found, and a fragile gem can't crash the install.
+- **The delegation trigger.** Install also writes a registry-generated block into
+  the host's `CLAUDE.md`/`AGENTS.md` telling the host agent to delegate to these
+  locals. This is what makes delegation actually happen.
+- **Direct-dependency scope.** Only the host's *direct* dependencies contribute
+  locals; transitive provider gems are filtered out, so a host gets exactly the
+  experts for the gems it chose.
+
+### Install (in any gem or app)
+
+1. Add the gem to the host's `Gemfile` (until it is on RubyGems, use a git
+   source: `gem "the_local", github: "DYB-Development/the_local"`), then
+   `bundle install`.
+2. Run `bundle exec the_local install`. This syncs every direct provider's
+   committed locals into `.claude/agents/` and writes the delegation trigger
+   into `CLAUDE.md`/`AGENTS.md`. It needs no Rails — a plain gem installs the
+   same way an app does.
+3. Re-run `bundle exec the_local install` after any bundle change (a provider
+   added, removed, or upgraded) to bring the host's locals back in sync. The
+   shell can automate this; the gem only exposes the command.
+
+Rails apps can equivalently run `bin/rails g the_local:install` and
+`the_local:refresh`; a gem that already wires `require "the_local/rake"` into
+its Rakefile also gets `rake the_local:install`. All three share one engine.
+
+### Author a provider (turn a gem into a provider)
+
+1. Run `bin/rails g the_local:provider <gem_name>` (pass `--scope`,
+   `--prefix`, `--worker` as needed). It scaffolds `lib/<gem>/reference.rb`, a
+   `lib/<gem>/reference/guide.md`, and a `lib/<gem>/the_local.rb` companion that
+   registers the standard interface; hooks `the_local:build` into the `Rakefile`;
+   requires the companion from the gem entrypoint; and builds the committed
+   `.md` for review.
+2. Write `guide.md` in this format — it is the single source of truth and is
+   embedded verbatim into every local. Document *your own* gem only: what it
+   does, how to install it, the conventions to enforce. Name companion gems but
+   do not explain their internals.
+3. Tailor the register block bodies and `scope` to your gem; the standard
+   interface is `info` (read-only explainer), `install` (sets the gem up in a
+   host), and a domain worker (`develop` for libraries, `operate` for CLIs).
+4. Run `rake the_local:build`, then **commit and ship**
+   `lib/<gem>/the_local/agents/*.md` (they must be in the gemspec's `files`).
+   This is the whole contract: a host discovers your locals by reading these
+   committed files from your gem on disk — it never loads your gem or runs your
+   register block — so if they aren't committed and shipped, you contribute
+   nothing, and if they are, you contribute everything. A drift test asserting
+   each committed file equals its `agent.to_markdown` keeps the artifact honest.
+
+### TheLocal.register
+
+```ruby
+TheLocal.register("my_gem", prefix: "my_gem", scope: "one-line domain phrase",
+                  agents_dir: File.expand_path("the_local/agents", __dir__)) do |c|
+  c.agent "info",
+    description: "Use to learn what my_gem offers.",
+    tools: "Read",
+    body: "You explain my_gem, answering only from the reference. You make no changes.",
+    knowledge: MyGem::Reference.content
+end
+```
+
+- `gem_name` (first arg) filters to a host's direct dependencies.
+- `prefix` is the agent filename namespace; defaults to the gem name.
+- `scope` is a one-line domain phrase used to generate the delegation trigger.
+- `agents_dir` is the absolute path to the committed `.md` files; each agent
+  records its `source_path` there so the installer can copy it verbatim.
+
+### Conventions
+
+- The register block lives behind `begin require "the_local" … rescue LoadError`
+  so the gem still works when the_local is absent.
+- `guide.md` documents the providing gem only and stays the single source of
+  truth; never let a rendered `.md` drift from `agent.to_markdown`.
+- Commit the rendered `.md`; never render in the host at install time.

data/lib/the_local/the_local.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "reference"
+
+module TheLocal
+  # Registers the_local's own locals (info / install / develop) with the_local,
+  # so the engine dogfoods the same provider model every other gem uses.
+  module Companion
+    SCOPE = "Claude Code locals: gems register subagents, the_local builds " \
+            "committed .md and installs them into a host app"
+
+    # rubocop:disable Metrics/MethodLength, Metrics/BlockLength
+    def self.register!
+      TheLocal.register(
+        "the_local",
+        scope: SCOPE,
+        agents_dir: File.expand_path("the_local/agents", __dir__)
+      ) do |c|
+        c.agent "info",
+                description: "Use to learn how the_local works — providers, the build/install " \
+                             "model, the delegation trigger, and the direct-dependency scope rule.",
+                tools: "Read",
+                body: "You explain how the_local works, answering only from the reference: providers " \
+                      "register locals, the_local:build renders committed .md, install/refresh copy " \
+                      "them verbatim into a host, the CLAUDE.md delegation trigger makes the host " \
+                      "delegate, and only direct dependencies contribute. You make no changes.",
+                knowledge: TheLocal::Reference.content
+
+        c.agent "install",
+                description: "Use to add the_local to a host app and set it up correctly.",
+                tools: "Bash, Read, Edit",
+                body: "You set the_local up in a host gem or app, following the reference's install " \
+                      "section exactly: add the gem (git source until it is on RubyGems), bundle, run " \
+                      "`bundle exec the_local install` to sync locals into .claude/agents/ and write " \
+                      "the delegation trigger, and re-run it after bundle changes. You do not invent " \
+                      "steps the reference does not list.",
+                knowledge: TheLocal::Reference.content
+
+        c.agent "develop",
+                description: "Use PROACTIVELY to turn a gem into a the_local provider — scaffolding " \
+                             "the companion, authoring the guide, and committing the rendered locals. " \
+                             "MUST BE USED instead of wiring a provider by hand.",
+                tools: "Read, Write, Edit, Grep",
+                body: "You turn a gem into a the_local provider following the reference's " \
+                      "provider-author workflow: run `the_local:provider`, write guide.md as the " \
+                      "single source of truth (your own gem only), tailor the register block, and " \
+                      "hook the_local:build into the Rakefile. The deliverable is the committed, " \
+                      "shipped lib/<gem>/the_local/agents/*.md — that is the whole contract a host " \
+                      "reads from disk; a host never loads the gem, so unless those files are built, " \
+                      "committed, and in the gemspec, the gem contributes nothing. You keep them in " \
+                      "sync with agent.to_markdown.",
+                knowledge: TheLocal::Reference.content
+      end
+    end
+    # rubocop:enable Metrics/MethodLength, Metrics/BlockLength
+  end
+end
+
+TheLocal::Companion.register!

data/lib/the_local/trigger_writer.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module TheLocal
+  # Writes the mandatory delegation trigger — the standing rule, read at the
+  # start of every session, that tells the host agent to delegate to its locals
+  # rather than work from memory. Generated from the registry's providers,
+  # filtered to the host's allowed gems. Plain Ruby; the Rails generator wraps it.
+  class TriggerWriter
+    BEGIN_MARKER = "<!-- the_local:begin -->"
+    END_MARKER = "<!-- the_local:end -->"
+
+    def initialize(registry:, destination:, allowed_gems:, filename: "CLAUDE.md")
+      @registry = registry
+      @destination = destination
+      @allowed_gems = allowed_gems
+      @filename = filename
+    end
+
+    def call
+      path = File.join(@destination, @filename)
+      existing = File.exist?(path) ? File.read(path) : ""
+      File.write(path, "#{merge(existing)}\n")
+    end
+
+    def rule
+      <<~MARKDOWN.chomp
+        #{BEGIN_MARKER}
+        ## Delegate to your locals
+
+        This project has installed expert subagents. Before doing work yourself,
+        check whether a local owns it and delegate — never work from memory on
+        something a local covers:
+
+        #{bullets.join("\n")}
+
+        See each agent's description for specifics.
+        #{END_MARKER}
+      MARKDOWN
+    end
+
+    private
+
+    # Replaces an existing marked section in place, or appends one, so re-running
+    # re-syncs the rule without duplicating or clobbering the host's own content.
+    def merge(existing)
+      section = /#{Regexp.escape(BEGIN_MARKER)}.*?#{Regexp.escape(END_MARKER)}/m
+      return existing.sub(section, rule) if existing.match?(section)
+      return rule if existing.strip.empty?
+
+      "#{existing.chomp}\n\n#{rule}"
+    end
+
+    def bullets
+      allowed_providers.map do |provider|
+        target = "#{provider.prefix}-* agents"
+        "- #{[provider.scope, target].compact.join(" → ")}"
+      end
+    end
+
+    def allowed_providers
+      @registry.providers.select { |provider| @allowed_gems.include?(provider.gem_name) }
+    end
+  end
+end

data/lib/the_local/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TheLocal
+  VERSION = "0.1.0"
+end

data/lib/the_local.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "the_local/version"
+require_relative "the_local/agent"
+require_relative "the_local/registry"
+require_relative "the_local/installer"
+require_relative "the_local/trigger_writer"
+require_relative "the_local/process_doc_writer"
+require_relative "the_local/scope"
+require_relative "the_local/sync"
+require_relative "the_local/refresh"
+require_relative "the_local/disk_providers"
+
+# Resident Claude Code expert subagents ("locals"), contributed by the gems and
+# app that register with it and installed into a consuming app's .claude/agents/.
+module TheLocal
+  class Error < StandardError; end
+
+  class << self
+    def registry
+      @registry ||= Registry.new
+    end
+
+    # Providers (gems or the app) call this at load time to contribute their
+    # agents. The first argument is the providing gem's name (used to filter to a
+    # host's direct dependencies); +prefix+ is the agent filename namespace and
+    # defaults to the gem name; +scope+ is a one-line phrase describing the
+    # provider's domain, used to generate the delegation trigger. +agents_dir+
+    # is the absolute path to the provider's committed, pre-rendered .md files
+    # (e.g. File.expand_path("the_local/agents", __dir__)); when given, each
+    # agent records its source_path there for the host installer to copy:
+    #
+    #   TheLocal.register("keystone_ui", prefix: "keystone", scope: "UI work") do |c|
+    #     c.agent "scaffold", description: "…", tools: "…", body: "…", knowledge: "…"
+    #   end
+    def register(gem_name, prefix: gem_name, scope: nil, agents_dir: nil)
+      registry.add_provider(Provider.new(gem_name: gem_name, prefix: prefix, scope: scope))
+      yield Collector.new(gem_name, prefix, registry, agents_dir: agents_dir)
+    end
+
+    def reset!
+      registry.clear
+    end
+  end
+end
+
+# In a Rails host, expose the the_local:refresh rake task. Skipped outside Rails
+# so the gem core stays Rails-free.
+require_relative "the_local/railtie" if defined?(Rails::Railtie)
+
+require_relative "the_local/the_local"

data/sig/the_local.rbs

@@ -0,0 +1,4 @@
+module TheLocal
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: the_local
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- tylercschneider
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-06-11 00:00:00.000000000 Z
+dependencies: []
+description: the_local lets any gem or app declare Claude Code subagents ("locals")
+  that know its conventions, and installs the aggregated set from every installed
+  provider into a consuming app's .claude/agents/ — plus a delegation rule so the
+  app's agent actually uses them.
+email:
+- tylercschneider@gmail.com
+executables:
+- the_local
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- PROVIDERS.md
+- README.md
+- Rakefile
+- exe/the_local
+- lib/generators/the_local/install_generator.rb
+- lib/generators/the_local/provider_generator.rb
+- lib/generators/the_local/templates/guide.md.tt
+- lib/generators/the_local/templates/reference.rb.tt
+- lib/generators/the_local/templates/the_local.rb.tt
+- lib/the_local.rb
+- lib/the_local/agent.rb
+- lib/the_local/builder.rb
+- lib/the_local/cli.rb
+- lib/the_local/disk_providers.rb
+- lib/the_local/installer.rb
+- lib/the_local/process_doc_writer.rb
+- lib/the_local/process_rules.rb
+- lib/the_local/process_rules/develop_process_rules.md
+- lib/the_local/railtie.rb
+- lib/the_local/rake.rb
+- lib/the_local/reference.rb
+- lib/the_local/reference/guide.md
+- lib/the_local/refresh.rb
+- lib/the_local/registry.rb
+- lib/the_local/scope.rb
+- lib/the_local/sync.rb
+- lib/the_local/tasks/the_local.rake
+- lib/the_local/the_local.rb
+- lib/the_local/the_local/agents/the_local-develop.md
+- lib/the_local/the_local/agents/the_local-info.md
+- lib/the_local/the_local/agents/the_local-install.md
+- lib/the_local/trigger_writer.rb
+- lib/the_local/version.rb
+- sig/the_local.rbs
+homepage: https://github.com/DYB-Development/the_local
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/DYB-Development/the_local
+  source_code_uri: https://github.com/DYB-Development/the_local/tree/main
+  bug_tracker_uri: https://github.com/DYB-Development/the_local/issues
+  changelog_uri: https://github.com/DYB-Development/the_local/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message: |
+  the_local is installed. To copy its Claude Code agents into this project, run:
+
+      bundle exec the_local install
+
+  That installs the locals contributed by your direct dependencies into
+  .claude/agents/ and writes the delegation trigger. Re-run it after bundle changes.
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: Resident Claude Code expert subagents, contributed by the gems an app uses.
+test_files: []