lyman 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42c4c9146ed53714fa0725775e91ffcbc599e485d652e84d483dedca2f47e047
-  data.tar.gz: e17d5dde1e338e8bae43cb97f5633b0cd4e24e06d66535bafdd2ff74319c9764
+  metadata.gz: c688da4f3dbae3ea1eae1ddadbbcb9c8024ca15d6b396d6a2b8aa85dd77bb91c
+  data.tar.gz: 31ead51a810ff07e2ef56943f36cc379ef8df8cbb7dcdfc611ad92c2d098c61e
 SHA512:
-  metadata.gz: 48c20fb9bb06c5f685b47491cc3d96cf33e7835b7b44bc1723bd87feec82a75d334b923a38c5d5838595bba31697e958e150dad4a5305e113edb454bcfd53e17
-  data.tar.gz: 26e9984e59ddc9722cb50bac1a3567cf9c424367c8dbed5e48bbf6b47fe3051052c59cd9e24a83fd5c7b49a81f056b2b256de89dda000c92798d536e072a8d5f
+  metadata.gz: f5c814ed46a0ff60e7058850901a13a4b5367a87afe935efcdc86c881619580a656e5387e9cedd47c9e7ea47caf958ffb2ddb73b6a4697563f6dac21995a4a05
+  data.tar.gz: a6b3450171f5db5c04eb8ce3bb5e3fb742abf692d45f30c1dcb1077afda75570e73b2e0a054fbeadcbca92d1876a5b17ed51cf8f9b07c6c444e1b86d9c6fddfe

data/README.md

@@ -152,9 +152,15 @@ Early and moving. What exists today: the vision, circuit-pattern, and
 deployment design docs, the core `Conversation` item, chat-completion and
 tool-execution workers, a working tool-using chat harness against live local
 models, and the generator CLI (`new` / `add` / `update` / `eject` / `diff` /
-`doctor` / `list`) with a Minitest suite behind it. Not yet published to
-rubygems.org — for now, run it from a checkout. On deck: publishing the gem,
-tool-call fan-out, and a one-shot (non-REPL) harness.
+`doctor` / `list`) with a Minitest suite behind it. Published to
+[rubygems.org](https://rubygems.org/gems/lyman) — install it with:
+
+```sh
+gem install lyman
+lyman new my-agent
+```
+
+On deck: tool-call fan-out and a one-shot (non-REPL) harness.
 
 ## License
 

data/docs/design/deployment.md

@@ -150,7 +150,12 @@ Three channels, ordered by reach:
    `AGENTS.md`) as a first-class artifact carrying the load-bearing facts: the
    nil-source footgun, the runaway-turn guard, item-as-control discipline,
    wire-vs-conversation separation. Highest-value channel: works with any
-   coding agent, zero install steps, travels with the code.
+   coding agent, zero install steps, travels with the code. For projects that
+   already have a `CLAUDE.md` lyman shouldn't clobber, the same guidance
+   ships as an opt-in Claude Code skill (`lyman add claude_skill` plants
+   `.claude/skills/lyman/SKILL.md`); `lyman add claude_md` points there when
+   it refuses to overwrite an existing file. Opt-in artifacts (`optional:` in
+   the registry) are skipped by `new` and reached with `add`.
 2. **A Claude plugin marketplace** in the `joelhelbling/lyman` repo, for
    richer *procedures* — e.g. a skill that knows how to wire a new tool worker
    correctly, or how to read a stalled pipeline. Skills earn their keep when

data/lib/lyman/cli/commands/add.rb

@@ -31,8 +31,13 @@ module Lyman
             end
           else
             if File.exist?(dest) && !force
-              raise Thor::Error, "#{dest} already exists and isn't tracked by lyman. " \
+              message = "#{dest} already exists and isn't tracked by lyman. " \
                 "Move it aside, or run `lyman add #{name} --force` to overwrite it."
+              if (alt = spec[:alternative])
+                message += " Or plant `lyman add #{alt}` instead, " \
+                  "which leaves #{spec[:dest]} untouched."
+              end
+              raise Thor::Error, message
             end
           end
 

data/lib/lyman/cli/commands/new.rb

@@ -19,7 +19,7 @@ module Lyman
           FileUtils.mkdir_p(project_root)
 
           manifest = Manifest.load(project_root)
-          Registry::ARTIFACTS.each do |artifact_name, spec|
+          Registry.default.each do |artifact_name, spec|
             plant(manifest, artifact_name, spec, project_root)
           end
           manifest.save

data/lib/lyman/cli/registry.rb

@@ -42,8 +42,21 @@ module Lyman
           source: "templates/CLAUDE.md",
           dest: "CLAUDE.md",
           role: :owned,
+          alternative: "claude_skill",
           description: "Guidance for coding agents working in this project"
         },
+        # The same guidance as claude_md, packaged as a Claude Code skill —
+        # for projects that already have a CLAUDE.md lyman shouldn't clobber.
+        # `optional:` keeps `new` from planting it (a fresh scaffold gets
+        # claude_md instead); `alternative:` on claude_md points here when
+        # `add` refuses to overwrite an existing CLAUDE.md.
+        "claude_skill" => {
+          source: "templates/SKILL.md",
+          dest: ".claude/skills/lyman/SKILL.md",
+          role: :owned,
+          optional: true,
+          description: "Claude Code skill variant of the CLAUDE.md guidance — for projects with their own CLAUDE.md"
+        },
         "gemfile" => {
           source: "templates/Gemfile",
           dest: "Gemfile",
@@ -90,6 +103,13 @@ module Lyman
         ARTIFACTS.select { |_, spec| spec[:role] == :managed }
       end
 
+      # What `new` plants: everything except opt-in artifacts (those exist
+      # for situations a fresh scaffold can't be in, like a pre-existing
+      # CLAUDE.md — reach them with `lyman add`).
+      def self.default
+        ARTIFACTS.reject { |_, spec| spec[:optional] }
+      end
+
       def self.source_path(spec, source_root: GEM_ROOT)
         File.join(source_root, spec[:source])
       end

data/lib/lyman/cli/version.rb

@@ -2,6 +2,6 @@ module Lyman
   module CLI
     # The gem's own version — distinct from any artifact's `planted_at`.
     # This is what the manifest's top-level `lyman:` key records.
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/lyman/cli.rb

@@ -80,7 +80,8 @@ module Lyman
               entry ? entry["status"] : "not planted"
             end
 
-          line = "#{name} (#{spec[:role]}) #{spec[:dest]}#{" — #{status}" if status} — #{spec[:description]}"
+          role = "#{spec[:role]}#{", opt-in" if spec[:optional]}"
+          line = "#{name} (#{role}) #{spec[:dest]}#{" — #{status}" if status} — #{spec[:description]}"
           say line
         end
       end

data/templates/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: lyman
+description: Guidance for working in a lyman-scaffolded agentic harness — the pipeline-of-workers model, the managed/owned boundary, and lyman's sharp edges. Use when reading or changing the harness (harness/chat.rb), anything under lib/lyman/, or when running lyman CLI commands (add, update, eject, diff, doctor).
+---
+
+# Working in a lyman project
+
+This project was scaffolded by [lyman](https://github.com/joelhelbling/lyman):
+an agentic harness built on the [shifty](https://github.com/joelhelbling/shifty)
+gem's pipeline-of-workers model. `harness/chat.rb` wires a model⇄tool loop
+against any OpenAI-compatible chat completions endpoint (Ollama by default).
+
+## Running it
+
+- `bundle install` — install dependencies (just `shifty` and `ostruct`; this
+  project has no runtime dependency on the `lyman` gem itself).
+- `ruby harness/chat.rb` — run the interactive chat harness. Defaults to
+  Ollama at `http://localhost:11434/v1`; override with `LYMAN_MODEL` and
+  `LYMAN_BASE_URL` env vars.
+
+## The managed/owned boundary
+
+Everything under the `Lyman::` namespace (`lib/lyman.rb`, `lib/lyman/`) is
+**managed** by the lyman CLI: it was planted here, and `lyman update` can
+refresh it from newer lyman releases. Treat it as a library to extend, not a
+file to hand-edit — if you need to change one, run `lyman eject <name>` first,
+which takes ownership explicitly rather than leaving it silently forked.
+`.lyman/manifest.yml` is the record of what's managed, what's owned, and what
+you've ejected; commit it.
+
+`harness/chat.rb` and everything outside `Lyman::` is **owned** — yours from
+day one, never touched by `lyman update`. Put your own workers in your own
+namespace or directory, not inside `lib/lyman/`.
+
+## Four load-bearing facts
+
+1. **The nil-source footgun.** In shifty, a source returning `nil` ends the
+   stream permanently. If you're driving a pipeline off a queue, enqueue
+   before you shift — never pull a source worker while its queue is empty.
+
+2. **The runaway-turn guard.** The model⇄tool circuit is bounded by
+   `Conversation#runaway?` / `max_rounds`. Keep that guard intact when
+   rewiring the circuit; without it, a model that keeps calling tools never
+   lets a turn end.
+
+3. **Item-as-control discipline.** An item may tell a worker *whether* to
+   act, never *which of several things* to do. A worker that switches
+   between jobs based on item state is the anti-pattern to avoid
+   (multi-way dispatch) — split it into stages, or use a splitter, instead.
+
+4. **Wire vs. conversation.** Reasoning/thinking content stays on messages in
+   the `Conversation` for observability, but `Workers.wire_messages` strips
+   it before anything goes out over the wire. Preserve that separation if
+   you touch message handling.
+
+## Other conventions
+
+- `lyman doctor` smoke-tests the pipeline end to end against a stub
+  transport — run it after `lyman update` or whenever something feels off.
+- `lyman list` shows what's managed, owned, or ejected in this project.
+- Messages use string keys throughout, matching the OpenAI-compatible wire
+  format — no symbol-key message hashes.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lyman
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Joel Helbling
@@ -83,6 +83,7 @@ files:
 - lib/lyman/workers/tool_execution.rb
 - templates/CLAUDE.md
 - templates/Gemfile
+- templates/SKILL.md
 - templates/gitignore
 - templates/lib_lyman.rb
 homepage: https://github.com/joelhelbling/lyman