the_local 0.3.0 → 0.4.1

data/lib/the_local/creators/install.md

@@ -0,0 +1,79 @@
+---
+name: the_local-author-install
+description: Use to author (or refresh) a gem's `install` local — the step-by-step guide to hooking the gem into a consumer. Reads the gem's declared interface and current code, and writes the_local/agents/<gem>-install.md. Run inside the provider gem.
+tools: Read, Grep, Write
+---
+
+You author ONE file: `the_local/agents/<gem>-install.md`, where `<gem>` is the
+basename of the single `*.gemspec` in the current directory.
+
+## Your assignment is the manifest
+
+Read `the_local/interface.yml` first. The entry points listed under `install:` are
+your assignment — document those, all of them, and nothing else. Entry points
+listed under `develop:` belong to another local; documenting one here is an error
+the check will reject.
+
+You do not decide what the gem's public surface is. That decision is already made
+in the manifest. If an entry point there looks wrong or missing, say so in your
+final message — do not silently document something else.
+
+Copy the manifest's `scope:` line verbatim into your front matter.
+
+## Verify against the code, then hide it
+
+Read the files under `sources:` — the generators, the initializer templates, the
+migrations — so every command and every file it writes is exact. A README's
+install section states intent and may be stale; the code wins.
+
+Then hide all of it. Your reader is wiring this gem up from your file alone and
+will never open its source. No paths into the gem's own `lib/`, no private
+classes, no instruction to go read the gem. Name only the commands the developer
+runs and the host files those commands create or edit.
+
+## What this local is for
+
+Hooking the systems together so they work: adding the gem to a consumer and
+configuring it. Not how to build with it — that is the develop local's.
+
+Write it as ordered steps, top to bottom. Where setup takes a real decision — a
+choice between install paths, a value with no safe default, a companion gem that
+may or may not be wanted — state the choice and tell the local to ask the
+developer rather than pick. Surfacing that question is part of the job.
+
+Cut every sentence that is not a step or a fact needed to complete one. No
+history, no rationale, no asides.
+
+## The shape
+
+```
+---
+name: <gem>-install
+description: Use to hook <gem> into a project — <the declared setup tasks, named>.
+tools: Bash, Read, Edit
+scope: <copied verbatim from the manifest>
+---
+
+<one or two sentences: this local follows these steps exactly and invents none>
+
+## What <gem> is
+<one line: what it is, and when to hook it in>
+
+## Interface
+<one bullet per declared entry point, each leading with the command in backticks,
+then one line on what it does>
+
+## How to use it
+<numbered steps, in order: the command to run, the host files it touches, and any
+decision to put to the developer>
+
+## Conventions
+<post-install checks, re-sync rules, and what is out of scope>
+```
+
+## Before you finish
+
+- Every entry point under `install:` appears in your Interface as its own bullet.
+- Nothing declared under `develop:` appears anywhere in your file.
+- Re-read it with no access to the source. Could someone wire the gem up correctly
+  from these steps alone?

data/lib/the_local/disk_providers.rb

@@ -1,32 +1,40 @@
 # frozen_string_literal: true
 
+require_relative "agent"
+require_relative "front_matter"
+require_relative "registry"
+
 module TheLocal
-  # Discovers providers by reading their committed agent files straight from each
-  # bundled gem's path on disk — no gem code is loaded and no register block runs.
-  # The committed .md (the build-and-commit artifact) is the declarative contract;
-  # a provider contributes simply by shipping those files. Populates the same
-  # registry the install pipeline already reads, so Installer/TriggerWriter/Sync
-  # are unchanged.
   module DiskProviders
-    AGENTS_GLOB = File.join("lib", "**", "the_local", "agents", "*.md")
+    AGENTS_GLOB = File.join("the_local", "agents", "*.md")
+    LEGACY_AGENTS_GLOB = File.join("lib", "**", "the_local", "agents", "*.md")
 
     def self.load(registry:, specs:)
       specs.each { |spec| register(registry, spec) }
     end
 
+    def self.agent_files(path)
+      rendered = Dir.glob(File.join(path, AGENTS_GLOB))
+      rendered.any? ? rendered : Dir.glob(File.join(path, LEGACY_AGENTS_GLOB))
+    end
+
     def self.register(registry, spec)
-      files = Dir.glob(File.join(spec[:path], AGENTS_GLOB))
+      files = agent_files(spec[:path])
       return if files.empty?
 
       agents = files.map { |file| agent_from(spec[:name], file) }
-      registry.add_provider(Provider.new(gem_name: spec[:name], prefix: agents.first.prefix, scope: nil))
+      representative = agents.find(&:scope) || agents.first
+      registry.add_provider(
+        Provider.new(gem_name: spec[:name], prefix: representative.prefix, scope: representative.scope)
+      )
       agents.each { |agent| registry.add(agent) }
     end
 
     def self.agent_from(gem_name, file)
       prefix, _, name = File.basename(file, ".md").rpartition("-")
       Agent.new(gem_name: gem_name, prefix: prefix, name: name,
-                description: nil, tools: nil, body: nil, knowledge: nil, source_path: file)
+                description: nil, tools: nil, body: nil, knowledge: nil, source_path: file,
+                scope: FrontMatter.new(File.read(file)).scope)
     end
   end
 end

data/lib/the_local/format.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module TheLocal
+  module Format
+    FRONT_MATTER_KEYS = %w[name description tools scope].freeze
+
+    SECTIONS = ["## What", "## Interface", "## How to use it", "## Conventions"].freeze
+
+    def self.section(markdown, heading)
+      markdown[/^#{Regexp.escape(heading)}$\n(.*?)(?=^## |\z)/m, 1].to_s
+    end
+
+    def self.problems(markdown)
+      missing_keys(markdown) + missing_sections(markdown)
+    end
+
+    def self.missing_keys(markdown)
+      FRONT_MATTER_KEYS.reject { |key| markdown.match?(/^#{key}:/) }
+                       .map { |key| "missing key: #{key}" }
+    end
+
+    def self.missing_sections(markdown)
+      SECTIONS.reject { |section| markdown.include?(section) }
+              .map { |section| "missing section: #{section}" }
+    end
+  end
+end

data/lib/the_local/front_matter.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module TheLocal
+  class FrontMatter
+    BLOCK = /\A---\n.*?\n---\n/m
+
+    def initialize(text)
+      @text = text
+    end
+
+    def scope
+      parsed["scope"]
+    end
+
+    private
+
+    def parsed
+      matched = @text[BLOCK]
+      return {} unless matched
+
+      YAML.safe_load(matched) || {}
+    end
+  end
+end

data/lib/the_local/installer.rb

@@ -34,8 +34,8 @@ module TheLocal
     def ensure_committed!(agent)
       return if agent.source_path && File.exist?(agent.source_path)
 
-      raise Error, "the_local: #{agent.gem_name} registered #{agent.qualified_name} without a committed " \
-                   "agent file. Run `rake the_local:build` in #{agent.gem_name} and commit its the_local/agents/."
+      raise Error, "the_local: #{agent.gem_name} is missing the committed file for #{agent.qualified_name}. " \
+                   "Run `rake the_local:author` in #{agent.gem_name} and commit its the_local/agents/."
     end
   end
 end

data/lib/the_local/interface.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module TheLocal
+  class Interface
+    FILE = File.join("the_local", "interface.yml")
+
+    def self.at(gem_root)
+      path = File.join(gem_root, FILE)
+      new(File.exist?(path) ? YAML.safe_load_file(path) : nil)
+    end
+
+    def initialize(declaration)
+      @declaration = declaration || {}
+    end
+
+    def scope
+      @declaration["scope"]
+    end
+
+    def entry_points_for(facet)
+      @declaration[facet] || []
+    end
+  end
+end

data/lib/the_local/provider_check.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative "format"
+require_relative "front_matter"
+require_relative "interface"
+
+module TheLocal
+  class ProviderCheck
+    LOCALS = %w[info install develop].freeze
+
+    def initialize(gem_root)
+      @gem_root = gem_root
+    end
+
+    def problems
+      format_problems + scope_problems + interface_problems
+    end
+
+    private
+
+    def format_problems
+      existing_files.flat_map do |file|
+        Format.problems(File.read(file)).map { |problem| "#{File.basename(file)}: #{problem}" }
+      end
+    end
+
+    def scope_problems
+      return disagreement_problems if declared.scope.nil?
+
+      existing_files.reject { |file| FrontMatter.new(File.read(file)).scope == declared.scope }
+                    .map { |file| "#{File.basename(file)}: scope does not match the manifest" }
+    end
+
+    def disagreement_problems
+      scopes = existing_files.map { |file| FrontMatter.new(File.read(file)).scope }.compact.uniq
+      scopes.size > 1 ? ["the locals' scope lines disagree"] : []
+    end
+
+    def interface_problems
+      return [] if LOCALS.all? { |local| declared.entry_points_for(local).empty? }
+
+      LOCALS.select { |local| File.exist?(file_for(local)) }
+            .flat_map { |local| undocumented(local) + misdocumented(local) }
+    end
+
+    def undocumented(local)
+      declared.entry_points_for(local)
+              .reject { |entry_point| documented(local).any? { |span| span.include?(entry_point) } }
+              .map { |entry_point| "#{name_of(local)}: undocumented entry point: #{entry_point}" }
+    end
+
+    def misdocumented(local)
+      documented(local).reject { |span| declared_in(span) == local }
+                       .map { |span| "#{name_of(local)}: #{misplacement(span)}" }
+    end
+
+    def misplacement(span)
+      owner = declared_in(span)
+      owner ? "entry point declared for #{owner}: #{span}" : "undeclared entry point: #{span}"
+    end
+
+    def declared_in(span)
+      LOCALS.find do |local|
+        declared.entry_points_for(local).any? { |entry_point| span.include?(entry_point) }
+      end
+    end
+
+    def documented(local)
+      Format.section(File.read(file_for(local)), "## Interface").scan(/^\s*-\s+`([^`\n]+)`/).flatten
+    end
+
+    def declared
+      @declared ||= Interface.at(@gem_root)
+    end
+
+    def existing_files
+      LOCALS.map { |local| file_for(local) }.select { |file| File.exist?(file) }
+    end
+
+    def file_for(local)
+      File.join(@gem_root, "the_local", "agents", name_of(local))
+    end
+
+    def name_of(local)
+      "#{gem_name}-#{local}.md"
+    end
+
+    def gem_name
+      File.basename(Dir.glob(File.join(@gem_root, "*.gemspec")).first.to_s, ".gemspec")
+    end
+  end
+end

data/lib/the_local/rake.rb

@@ -2,17 +2,22 @@
 
 require "rake"
 require "the_local"
-require "the_local/builder"
+require "the_local/author"
+require "the_local/provider_check"
 
-# Gem-side build task. A provider adds `require "the_local/rake"` to its Rakefile
-# (after loading the gem, so its locals are registered) and runs
-# `rake the_local:build` to (re)render its committed .claude agent files from the
-# registered definitions. Host apps don't use this — they install/refresh.
 namespace :the_local do
-  desc "Render this provider's committed agent files from its registered definitions"
-  task :build do
-    written = TheLocal::Builder.new(registry: TheLocal.registry, validate: true).call
-    puts "the_local: built #{written.length} agent file(s)"
+  desc "Author this provider's committed locals from its current source"
+  task :author do
+    TheLocal::Author.new(gem_root: Dir.pwd).call
+    puts "the_local: authored locals; review the_local/agents/ and run `rake the_local:check`"
+  end
+
+  desc "Check this provider's committed locals hold the fixed format"
+  task :check do
+    problems = TheLocal::ProviderCheck.new(Dir.pwd).problems
+    raise TheLocal::Error, "the_local: malformed local(s):\n- #{problems.join("\n- ")}" if problems.any?
+
+    puts "the_local: locals hold the format"
   end
 
   desc "Install/refresh this project's locals from the current bundle into .claude/agents/"

data/lib/the_local/registry.rb

@@ -5,9 +5,8 @@ module TheLocal
   # one-line scope used to generate the delegation trigger.
   Provider = Data.define(:gem_name, :prefix, :scope)
 
-  # Accumulates the providers and agents contributed by everything that calls
-  # TheLocal.register. The install generator reads this to write .claude/agents/
-  # and the delegation trigger.
+  # Accumulates the providers and agents discovered from disk. Installer and
+  # TriggerWriter read this to write .claude/agents/ and the delegation trigger.
   class Registry
     def initialize
       @agents = []
@@ -29,31 +28,4 @@ module TheLocal
       @providers.clear
     end
   end
-
-  # Yielded to a provider's register block. Turns each `agent` call into an
-  # Agent tagged with the providing gem and namespaced under its prefix.
-  class Collector
-    def initialize(gem_name, prefix, registry, agents_dir: nil)
-      @gem_name = gem_name
-      @prefix = prefix
-      @registry = registry
-      @agents_dir = agents_dir
-    end
-
-    def agent(name, description:, tools:, body:, knowledge: nil)
-      @registry.add(
-        Agent.new(gem_name: @gem_name, prefix: @prefix, name: name,
-                  description: description, tools: tools, body: body, knowledge: knowledge,
-                  source_path: source_path_for(name))
-      )
-    end
-
-    private
-
-    def source_path_for(name)
-      return nil unless @agents_dir
-
-      File.join(@agents_dir, "#{@prefix}-#{name}.md")
-    end
-  end
 end

data/lib/the_local/trigger_writer.rb

@@ -19,7 +19,7 @@ module TheLocal
     def call
       path = File.join(@destination, @filename)
       existing = File.exist?(path) ? File.read(path) : ""
-      File.write(path, "#{merge(existing)}\n")
+      File.write(path, "#{merge(existing).chomp}\n")
     end
 
     def rule

data/lib/the_local/version.rb

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

data/lib/the_local.rb

@@ -11,7 +11,7 @@ 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/.
+# app a host depends on and installed into the host's .claude/agents/.
 module TheLocal
   class Error < StandardError; end
 
@@ -20,23 +20,6 @@ module TheLocal
       @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
@@ -46,5 +29,3 @@ 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/the_local/agents/the_local-develop.md

@@ -0,0 +1,48 @@
+---
+name: the_local-develop
+description: Use PROACTIVELY to author a gem's locals — declaring its public interface and running the authoring task — MUST BE USED instead of hand-writing a local.
+tools: Read, Write, Edit, Grep
+scope: resident Claude Code experts — authoring a gem's locals and installing them into a host
+---
+
+You author a gem's locals by declaring its interface and running the authoring
+task. You do not hand-write locals and you never read the_local's source. A
+provider carries no Ruby for the_local — a manifest and three committed files.
+
+## What the_local is
+
+The engine that installs gems' resident Claude Code locals into a host. Reach for
+this local whenever a gem should contribute locals, or when a change to its public
+interface may have made its locals stale.
+
+## Interface
+
+- `rake the_local:author` — writes the gem's locals into `the_local/agents/` from
+  its current source, one at a time, guided by the manifest.
+- `rake the_local:check` — verifies the committed locals against the manifest:
+  every declared entry point documented, nothing undeclared, nothing documented by
+  the wrong local.
+
+## How to use it
+
+1. Write `the_local/interface.yml` with the developer. It declares `scope`, the
+   entry points under `install` and `develop`, and the `sources` that define them.
+   This is the one judgment call in the process — ask which commands are the gem's
+   public surface rather than guessing, and confirm which of the two each belongs
+   to. An entry point may appear under exactly one.
+2. Run `rake the_local:author`. It writes `the_local/agents/<gem>-{info,install,develop}.md`.
+3. Run `rake the_local:check` and fix what it reports.
+4. Commit `the_local/`. For a packaged gem, confirm `the_local/**/*` is in the
+   gemspec's `files`, or it ships nothing.
+5. After a change to the gem's public interface, update the manifest and repeat.
+   An internal-only change needs nothing.
+
+## Conventions
+
+- The manifest is the contract. Never widen a local past what it declares; if the
+  gem gained a public entry point, declare it first.
+- Locals document the public interface only, never the gem's internals, and never
+  send a reader into the provider's source.
+- The three locals never overlap: **install** hooks the gem into a host,
+  **develop** uses it, **info** carries what fits neither.
+- Regenerate from current source rather than editing a stale local by hand.

data/the_local/agents/the_local-info.md

@@ -0,0 +1,40 @@
+---
+name: the_local-info
+description: Use to learn what the_local offers — resident expert subagents, the provider/consumer model, and the vocabulary the other locals assume.
+tools: Read
+scope: resident Claude Code experts — authoring a gem's locals and installing them into a host
+---
+
+You explain what the_local does, answering only from this reference. You make no
+changes, and you never read the_local's source.
+
+## What the_local is
+
+the_local lets any gem ship resident Claude Code expert subagents ("locals") that
+know its conventions. A **provider** gem commits its locals; a **consumer** host
+installs the locals of its direct dependencies into `.claude/agents/`, plus a
+delegation rule so the host's agent uses them.
+
+Reach for it when you want a gem's work done consistently — the host delegates
+that gem's tasks to its local instead of re-deriving conventions each time.
+
+## Interface
+
+the_local's commands are split across its other two locals, with no overlap.
+Hooking the_local into a project is the install local's; authoring a gem's own
+locals is the develop local's. Route to those rather than answering here.
+
+## How to use it
+
+Decide which side you are on. A host that wants its dependencies' expertise is a
+consumer and needs the install local. A gem that wants to contribute expertise is
+a provider and needs the develop local. A gem can be both.
+
+## Conventions
+
+- A **local** is one Claude Code subagent that knows one gem's public interface.
+- Each provider ships three: **info** explains, **install** hooks the gem into a
+  host, **develop** uses it. A command belongs to exactly one of them.
+- The committed `the_local/agents/*.md` are the whole contract a host reads — a
+  host never loads the provider gem.
+- Only a host's **direct** dependencies contribute locals.

data/the_local/agents/the_local-install.md

@@ -0,0 +1,49 @@
+---
+name: the_local-install
+description: Use to hook the_local into a gem or Rails app — installing dependencies' locals, the delegation trigger in CLAUDE.md, and the provider rake tasks.
+tools: Bash, Read, Edit
+scope: resident Claude Code experts — authoring a gem's locals and installing them into a host
+---
+
+You hook the_local into the host by following these steps exactly, in order. You
+do not invent steps, and you never read the_local's source.
+
+## What the_local is
+
+The engine that installs gems' resident Claude Code locals into a host and writes
+the delegation trigger. Hook it into any gem or app that wants its dependencies'
+locals, or that will contribute locals of its own.
+
+## Interface
+
+- `bundle exec the_local install` — installs direct dependencies' locals into
+  `.claude/agents/` and writes the trigger. Works anywhere; no Rails required.
+- `bin/rails g the_local:install` — the Rails equivalent of the above.
+- `rake the_local:refresh` — re-syncs a Rails host after a bundle change.
+- `rake the_local:install` — re-syncs a non-Rails host after a bundle change.
+- `bin/rails g the_local:provider` — adds the provider rake tasks to a gem, so it
+  can author locals of its own.
+
+## How to use it
+
+1. Add `gem "the_local"` to the host's `Gemfile` and run `bundle install`.
+2. Install the locals. In a Rails app run `bin/rails g the_local:install`;
+   anywhere else run `bundle exec the_local install`. Either copies every direct
+   dependency's committed locals into `.claude/agents/` and writes the delegation
+   block into `CLAUDE.md`/`AGENTS.md`.
+3. Tell the developer to restart their Claude Code session — agents load at
+   startup, so the new locals are inert until then.
+4. Re-sync after any bundle change with `rake the_local:refresh` in a Rails app or
+   `rake the_local:install` elsewhere.
+5. Only if the host is a gem that should contribute its own locals, run
+   `bin/rails g the_local:provider`. Confirm this with the developer first — it is
+   a separate decision from consuming locals, and it edits the Gemfile and Rakefile.
+
+## Conventions
+
+- Re-sync after every `bundle install`/`update`, or the host's locals drift from
+  its dependencies.
+- Install only reads committed files off disk — a dependency that shipped no
+  committed locals contributes nothing, and that is not an error.
+- Hooking up is all this local does. Authoring a gem's own locals is the develop
+  local's job.

data/the_local/interface.yml

@@ -0,0 +1,21 @@
+scope: resident Claude Code experts — authoring a gem's locals and installing them into a host
+
+install:
+  - bundle exec the_local install
+  - bin/rails g the_local:install
+  - rake the_local:refresh
+  - rake the_local:install
+  - bin/rails g the_local:provider
+
+develop:
+  - rake the_local:author
+  - rake the_local:check
+
+sources:
+  - lib/the_local/cli.rb
+  - lib/the_local/rake.rb
+  - lib/the_local/tasks/the_local.rake
+  - lib/generators/the_local/install_generator.rb
+  - lib/generators/the_local/provider_generator.rb
+  - lib/the_local/author.rb
+  - lib/the_local/provider_check.rb