the_local 0.3.0 → 0.4.0

data/lib/generators/the_local/templates/guide.md.tt

@@ -1,41 +0,0 @@
-## <%= module_name %>
-
-> **DO NOT** explore the <%= gem_name %> gem source code. This reference is the
-> complete user-facing API, embedded verbatim into every <%= gem_name %> local so
-> their guidance never drifts. Keep it the single source of truth.
->
-> The bar for everything below: a host agent must be able to do <%= gem_name %>
-> work from this guide alone — exact signatures and a complete, copy-paste
-> recipe — without ever opening <%= gem_name %>'s source. If a signature or step
-> is missing, the agent will dig into source, which is the cost the_local exists
-> to remove. Replace every TODO; `rake the_local:build` refuses a guide that
-> still has one.
-
-TODO: One paragraph — what <%= gem_name %> is and the problem it solves.
-
-### Interface
-
-TODO: The literal public API a host calls — every method/class/DSL entry with
-its exact signature: arguments, which are required vs optional, and what it
-returns. Give the signatures themselves, each with a one-line example, not prose
-about them. This is what the `info` and `<%= worker %>` locals answer from, so an
-agent never has to read source to recall how a call is shaped.
-
-### Recipe
-
-TODO: A complete, copy-paste implementation of the most common <%= gem_name %>
-task — the whole thing, not a fragment — so the `<%= worker %>` local reproduces
-it identically every time instead of re-deriving it from source.
-
-### Install
-
-TODO: The exact, correct steps to add <%= gem_name %> to a host and set it up —
-this is what the `install` local follows. Be specific to how <%= gem_name %> is
-actually installed (e.g. for a Rails engine: add the gem, `bundle install`,
-install + run migrations, wire any concerns/initializers). Don't leave it
-generic.
-
-### Conventions
-
-TODO: The conventions the `<%= worker %>` local must enforce when doing
-<%= gem_name %> work, so usage stays consistent across the host.

data/lib/generators/the_local/templates/reference.rb.tt

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-<%= open_module %>
-  # Single source of truth for <%= gem_name %>'s user-facing API, read by the
-  # the_local companion subagents so their guidance never drifts from the docs.
-  module Reference
-    DIR = File.expand_path("reference", __dir__)
-
-    def self.content
-      read("guide.md")
-    end
-
-    def self.read(name)
-      File.read(File.join(DIR, name)).chomp
-    end
-  end
-<%= close_module %>

data/lib/generators/the_local/templates/the_local.rb.tt

@@ -1,49 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "reference"
-
-<%= open_module %>
-  # Registers <%= gem_name %>'s locals (Claude Code subagents) with the_local.
-  # These are the common command interface every provider exposes to apps:
-  # `info` (read-only, explains the gem), `install` (sets it up in a host), and
-  # `<%= worker %>` (the proactive domain worker). Soft dependency: registration
-  # is a no-op when the_local is absent.
-  module Companion
-    def self.register!
-      TheLocal.register("<%= gem_name %>"<%= ", prefix: \"#{prefix}\"" unless prefix == gem_name %>, scope: "<%= scope %>",
-                        agents_dir: File.expand_path("the_local/agents", __dir__)) do |c|
-        c.agent "info",
-          description: "Use to learn what <%= gem_name %> offers — its API and conventions.",
-          tools: "Read",
-          body: "You explain what <%= gem_name %> does and how to use it, answering only from " \
-                "your reference. You make no changes, and you never read <%= gem_name %>'s " \
-                "source — the reference is the complete interface.",
-          knowledge: <%= module_name %>::Reference.content
-
-        c.agent "install",
-          description: "Use to add <%= gem_name %> to a project and set it up correctly.",
-          tools: "Bash, Read, Edit",
-          body: "You add <%= gem_name %> to the project and complete its setup by following your " \
-                "reference's Install section exactly, step by step. You do not invent steps it " \
-                "does not list, and you never read <%= gem_name %>'s source.",
-          knowledge: <%= module_name %>::Reference.content
-
-        c.agent "<%= worker %>",
-          description: "Use PROACTIVELY for any <%= gem_name %> work. MUST BE USED instead of " \
-                       "hand-rolling it. TODO: name the concrete tasks this local owns.",
-          tools: "Read, Write, Edit, Grep",
-          body: "You do <%= gem_name %> work by following the Interface, Recipe, and Conventions " \
-                "in your reference exactly, so usage stays consistent across the host. You " \
-                "implement from the reference, never from <%= gem_name %>'s source.",
-          knowledge: <%= module_name %>::Reference.content
-      end
-    end
-  end
-<%= close_module %>
-
-begin
-  require "the_local"
-  <%= module_name %>::Companion.register!
-rescue LoadError
-  # the_local not installed — <%= gem_name %> works standalone.
-end

data/lib/the_local/builder.rb

@@ -1,57 +0,0 @@
-# frozen_string_literal: true
-
-require "fileutils"
-
-module TheLocal
-  # Renders each registered agent's markdown to its committed source_path, so a
-  # provider gem can commit the files and the host installer later copies them
-  # verbatim (rather than rendering at install time). Plain Ruby — driven by the
-  # the_local:build rake task a provider runs. Agents that declared no agents_dir
-  # (and so have no source_path) are skipped: there is nowhere to write them.
-  class Builder
-    # A real placeholder is a line-leading "TODO:"; an inline mention of the
-    # marker (a guide documenting the convention) is left alone.
-    PLACEHOLDER = /^\s*TODO:/
-
-    # The canonical sections every guide must carry, so a consuming agent meets
-    # the same shape in every gem's local. Matched as header prefixes.
-    REQUIRED_SECTIONS = ["### Interface", "### Recipe", "### Install", "### Conventions"].freeze
-
-    def initialize(registry:, validate: false)
-      @registry = registry
-      @validate = validate
-    end
-
-    def call
-      validate! if @validate
-
-      buildable_agents.map do |agent|
-        FileUtils.mkdir_p(File.dirname(agent.source_path))
-        File.write(agent.source_path, agent.to_markdown)
-        agent.source_path
-      end
-    end
-
-    private
-
-    def validate!
-      problems = buildable_agents.flat_map { |agent| problems_for(agent) }
-      return if problems.empty?
-
-      raise Error, "the_local: incomplete guide(s):\n- #{problems.join("\n- ")}"
-    end
-
-    def problems_for(agent)
-      markdown = agent.to_markdown
-      problems = []
-      problems << "#{agent.qualified_name}: TODO: placeholders remain" if markdown.match?(PLACEHOLDER)
-      missing = REQUIRED_SECTIONS.reject { |section| markdown.include?(section) }
-      problems << "#{agent.qualified_name}: missing #{missing.join(", ")}" if missing.any?
-      problems
-    end
-
-    def buildable_agents
-      @registry.agents.select(&:source_path)
-    end
-  end
-end

data/lib/the_local/reference/guide.md

@@ -1,179 +0,0 @@
-## 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 `gem "the_local"` to the host's `Gemfile`, 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` to the canonical shape — the same sections in every
-   provider, so the consuming agent meets one structure everywhere and
-   `rake the_local:build` rejects a guide missing one:
-   - **Interface** — every public call's *exact signature* (arguments, required
-     vs optional, return) as real signatures in a code block, not prose.
-   - **Recipe** — a complete copy-paste implementation of the common task.
-   - **Install** — the exact setup steps for *this* gem.
-   - **Conventions** — what the worker enforces to keep usage consistent.
-
-   The bar: a host agent does your gem's work from the guide alone, without ever
-   opening your source. Document your own gem only; 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.
-
-### Interface
-
-The complete public surface — every entry point with its exact signature, so a
-local answers from here instead of reading source.
-
-**Register locals (provider Ruby, behind a soft `require "the_local"` guard):**
-
-```ruby
-TheLocal.register(gem_name, prefix: gem_name, scope: nil, agents_dir: nil) { |c| … }
-#   Registers a provider and yields a Collector. gem_name is positional and
-#   filters to a host's direct dependencies; prefix is the filename namespace
-#   (defaults to gem_name); scope is the one-line delegation phrase; agents_dir
-#   is the absolute path to the committed .md files (each agent records its
-#   source_path there for the installer to copy verbatim).
-
-c.agent(name, description:, tools:, body:, knowledge: nil)
-#   Declares one local. name is positional; description, tools, body are
-#   required; knowledge — a String or Array of Strings, usually
-#   MyGem::Reference.content — is optional and appended below the body.
-```
-
-```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
-```
-
-**Build (provider Rakefile, after `require "the_local/rake"`):**
-
-- `rake the_local:build` — renders each registered agent to its committed
-  `lib/<gem>/the_local/agents/<prefix>-<name>.md`. Refuses to render a guide that
-  still holds a `TODO:` placeholder or is missing a canonical section.
-- `rake the_local:install` — installs/refreshes this project's own locals.
-
-**Host (consuming app or gem):**
-
-- `bundle exec the_local install` — CLI; syncs direct providers' locals into
-  `.claude/agents/` and writes the delegation trigger. No Rails required.
-- `bin/rails g the_local:install` and `rake the_local:refresh` — Rails equivalents.
-- `bin/rails g the_local:provider <gem_name> [--prefix P] [--scope "…"] [--worker develop|operate]`
-  — scaffolds the provider wiring (Reference loader, guide, companion).
-
-### Recipe
-
-Turn a gem into a provider — the complete companion, copy-paste and rename:
-
-```ruby
-# lib/my_gem/the_local.rb
-require_relative "reference"
-
-module MyGem
-  module Companion
-    def self.register!
-      TheLocal.register("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 what my_gem does, answering only from your reference. " \
-                      "You make no changes and never read my_gem's source.",
-                knowledge: MyGem::Reference.content
-
-        c.agent "develop",
-                description: "Use PROACTIVELY for any my_gem work.",
-                tools: "Read, Write, Edit, Grep",
-                body: "You do my_gem work by following your reference's Interface, Recipe, " \
-                      "and Conventions exactly. You implement from the reference, never source.",
-                knowledge: MyGem::Reference.content
-      end
-    end
-  end
-end
-
-begin
-  require "the_local"
-  MyGem::Companion.register!
-rescue LoadError
-  # the_local not installed — my_gem works standalone.
-end
-```
-
-Then write `reference/guide.md` to the canonical shape, `rake the_local:build`,
-and commit `lib/my_gem/the_local/agents/*.md`.
-
-### 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/reference.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-
-module TheLocal
-  # Loads the_local's own knowledge guide, embedded verbatim into its locals.
-  module Reference
-    DIR = File.expand_path("reference", __dir__)
-
-    def self.content
-      read("guide.md")
-    end
-
-    def self.read(name)
-      File.read(File.join(DIR, name)).chomp
-    end
-  end
-end

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

@@ -1,187 +0,0 @@
----
-name: the_local-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
----
-
-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.
-
-## 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 `gem "the_local"` to the host's `Gemfile`, 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` to the canonical shape — the same sections in every
-   provider, so the consuming agent meets one structure everywhere and
-   `rake the_local:build` rejects a guide missing one:
-   - **Interface** — every public call's *exact signature* (arguments, required
-     vs optional, return) as real signatures in a code block, not prose.
-   - **Recipe** — a complete copy-paste implementation of the common task.
-   - **Install** — the exact setup steps for *this* gem.
-   - **Conventions** — what the worker enforces to keep usage consistent.
-
-   The bar: a host agent does your gem's work from the guide alone, without ever
-   opening your source. Document your own gem only; 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.
-
-### Interface
-
-The complete public surface — every entry point with its exact signature, so a
-local answers from here instead of reading source.
-
-**Register locals (provider Ruby, behind a soft `require "the_local"` guard):**
-
-```ruby
-TheLocal.register(gem_name, prefix: gem_name, scope: nil, agents_dir: nil) { |c| … }
-#   Registers a provider and yields a Collector. gem_name is positional and
-#   filters to a host's direct dependencies; prefix is the filename namespace
-#   (defaults to gem_name); scope is the one-line delegation phrase; agents_dir
-#   is the absolute path to the committed .md files (each agent records its
-#   source_path there for the installer to copy verbatim).
-
-c.agent(name, description:, tools:, body:, knowledge: nil)
-#   Declares one local. name is positional; description, tools, body are
-#   required; knowledge — a String or Array of Strings, usually
-#   MyGem::Reference.content — is optional and appended below the body.
-```
-
-```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
-```
-
-**Build (provider Rakefile, after `require "the_local/rake"`):**
-
-- `rake the_local:build` — renders each registered agent to its committed
-  `lib/<gem>/the_local/agents/<prefix>-<name>.md`. Refuses to render a guide that
-  still holds a `TODO:` placeholder or is missing a canonical section.
-- `rake the_local:install` — installs/refreshes this project's own locals.
-
-**Host (consuming app or gem):**
-
-- `bundle exec the_local install` — CLI; syncs direct providers' locals into
-  `.claude/agents/` and writes the delegation trigger. No Rails required.
-- `bin/rails g the_local:install` and `rake the_local:refresh` — Rails equivalents.
-- `bin/rails g the_local:provider <gem_name> [--prefix P] [--scope "…"] [--worker develop|operate]`
-  — scaffolds the provider wiring (Reference loader, guide, companion).
-
-### Recipe
-
-Turn a gem into a provider — the complete companion, copy-paste and rename:
-
-```ruby
-# lib/my_gem/the_local.rb
-require_relative "reference"
-
-module MyGem
-  module Companion
-    def self.register!
-      TheLocal.register("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 what my_gem does, answering only from your reference. " \
-                      "You make no changes and never read my_gem's source.",
-                knowledge: MyGem::Reference.content
-
-        c.agent "develop",
-                description: "Use PROACTIVELY for any my_gem work.",
-                tools: "Read, Write, Edit, Grep",
-                body: "You do my_gem work by following your reference's Interface, Recipe, " \
-                      "and Conventions exactly. You implement from the reference, never source.",
-                knowledge: MyGem::Reference.content
-      end
-    end
-  end
-end
-
-begin
-  require "the_local"
-  MyGem::Companion.register!
-rescue LoadError
-  # the_local not installed — my_gem works standalone.
-end
-```
-
-Then write `reference/guide.md` to the canonical shape, `rake the_local:build`,
-and commit `lib/my_gem/the_local/agents/*.md`.
-
-### 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.