@zalom/plastic 1.1.5 → 1.3.0

package/scripts/lib/installer_core.rb

@@ -18,10 +18,39 @@ class InstallerCore
 
   DEFAULT_AGENTS = [
     { key: "claude", name: "Claude Code", dir: File.join(Dir.home, ".claude"), flag: "--claude" },
-    { key: "codex", name: "Codex CLI", dir: File.join(Dir.home, ".agents"), flag: "--codex" },
+    { key: "codex", name: "Codex CLI", dir: File.join(Dir.home, ".agents"),
+      home_dir: File.join(Dir.home, ".codex"), flag: "--codex" },
     { key: "hermes", name: "Hermes", dir: File.join(Dir.home, ".hermes"), flag: "--hermes" },
   ].freeze
 
+  # Codex AGENTS.md marked-section markers (single source of truth; doctor.rb
+  # matches these literals structurally, so keep the two in sync by hand).
+  CODEX_SECTION_BEGIN_PREFIX = "<!-- BEGIN PLASTIC INTEGRATION"
+  CODEX_SECTION_END = "<!-- END PLASTIC INTEGRATION -->"
+
+  # Regex matching exactly one managed section (BEGIN line .. END line), non-greedy.
+  CODEX_SECTION_RE = /^<!-- BEGIN PLASTIC INTEGRATION.*?-->\n.*?\n<!-- END PLASTIC INTEGRATION -->\n?/m
+
+  # Curated essentials plus a pointer to ~/.plastic/PLASTIC.md, injected into
+  # ~/.codex/AGENTS.md. Not a slice of PLASTIC.md (which is already over the 32 KiB
+  # AGENTS.md merge cap on its own), so it never drifts and carries no maintenance fork.
+  CODEX_AGENTS_MD_BODY = <<~MD.freeze
+    Plastic is installed for this agent. Plastic is intent-driven state management: all
+    work flows through an intent, moved through What, Why, How, then Exec. Do not jump
+    straight to code.
+
+    Standing rules:
+    - The full conventions live in ~/.plastic/PLASTIC.md. Read it and follow it exactly.
+      It is generated and overwritten on Plastic updates, so never edit it.
+    - Operational procedures are installed as skills under ~/.agents/skills/ (each
+      plastic-<name>/SKILL.md). Use them for the lifecycle work they describe.
+    - Intents, specs, plans, checklists, and outcomes live under ~/.plastic/, never in
+      the project tree.
+
+    This section is managed by the Plastic installer. It is replaced on update and removed
+    on uninstall. Do not edit anything between the BEGIN and END markers.
+  MD
+
   attr_reader :package_root, :plastic_home, :version, :agents
 
   def initialize(package_root:, plastic_home: DEFAULT_PLASTIC_HOME, version: nil, agents: DEFAULT_AGENTS)
@@ -278,6 +307,8 @@ class InstallerCore
       "scripts/new-intent" => "scripts/new-intent",
       "scripts/end-intent" => "scripts/end-intent",
       "scripts/hook-create-gate" => "scripts/hook-create-gate",
+      "scripts/lib/apply_patch_envelope.rb" => "scripts/lib/apply_patch_envelope.rb",
+      "scripts/codex-hook" => "scripts/codex-hook",
       "templates/intent.md" => "templates/intent.md",
       "templates/spec.md" => "templates/spec.md",
       "templates/plan.md" => "templates/plan.md",
@@ -434,12 +465,16 @@ class InstallerCore
       installed << dest
     end
 
-    # Copy skills as flat, hyphen-namespaced personal skills (plastic-<name>/)
+    # Copy skills as flat, hyphen-namespaced personal skills (plastic-<name>/).
+    # advisor.enabled: false skips the agent-advisor skill along with both
+    # advisor agents below, so a user who declined the advisor never sees a
+    # dead-end skill pointing at nothing installed.
     skills_source = File.join(package_root, "skills")
-    installed += install_skills_flat(skills_source, skills_root) if File.directory?(skills_source)
+    skill_exclude = advisor_enabled? ? [] : ["agent-advisor"]
+    installed += install_skills_flat(skills_source, skills_root, exclude: skill_exclude) if File.directory?(skills_source)
 
     # Copy agent role files into <dir>/agents (manifest-tracked, pruned on update)
-    installed += install_agents(File.join(config[:dir], "agents"), models: agent_model_overrides)
+    installed += install_agents(File.join(config[:dir], "agents"), models: agent_model_overrides, advisor_enabled: advisor_enabled?)
 
     # Write VERSION
     version_file = File.join(plastic_dir, "VERSION")
@@ -464,18 +499,166 @@ class InstallerCore
   def install_codex(config, force)
     installed = []
     skills_source = File.join(package_root, "skills")
-    installed += install_skills_flat(skills_source, File.join(config[:dir], "skills")) if File.directory?(skills_source)
-    installed += install_agents(File.join(config[:dir], "agents"), models: agent_model_overrides)
+    skill_exclude = advisor_enabled? ? [] : ["agent-advisor"]
+    installed += install_skills_flat(skills_source, File.join(config[:dir], "skills"), exclude: skill_exclude) if File.directory?(skills_source)
+    # Codex-scoped overrides only (agents.models.codex.*): a literal Claude
+    # model id set under agents.models.claude.* (or the legacy flat form,
+    # which resolves as claude) must never reach a Codex TOML.
+    installed += generate_codex_agents(File.join(config[:home_dir], "agents"), models: agent_model_overrides(harness: "codex"))
+
+    # Instruction injection (L1): Plastic standing conventions into ~/.codex/AGENTS.md.
+    # Partial-ownership file, so it is NOT manifest-tracked (stripped surgically on uninstall).
+    FileUtils.mkdir_p(config[:home_dir])
+    inject_codex_agents_md(File.join(config[:home_dir], "AGENTS.md"))
+
+    # L3 hooks (intent 102): register into ~/.codex/hooks.json (user scope, defeats the
+    # worktree bug). Partial-ownership file, so it is merged and NOT manifest-tracked
+    # (stripped surgically on uninstall), same treatment as AGENTS.md.
+    merge_codex_hooks(File.join(config[:home_dir], "hooks.json"))
 
     write_manifest(installed, File.join(config[:dir], "plastic-manifest.json"))
     { agent: config[:name], success: true, files: installed.size }
   end
 
+  # --- Codex agent TOML generation (intent 102a) ---
+  #
+  # Codex reads standalone TOML agent files at ~/.codex/agents/*.toml (config[:home_dir]),
+  # never the ~/.agents/agents/*.md copy the shared install_agents writes (that root is
+  # the cross-tool skills standard, not an agents root). The codex leg therefore generates
+  # a whole-file, Plastic-owned .toml per repo agents/*.md instead of copying markdown.
+  # The returned paths append to `installed`, so they are manifest-tracked and pruned on
+  # uninstall by the manifest whole-file-delete path, exactly like ~/.claude/agents/*.md.
+  def generate_codex_agents(agents_root, models: {})
+    sources = Dir.glob(File.join(package_root, "agents", "*.md"))
+    return [] if sources.empty?
+
+    FileUtils.mkdir_p(agents_root)
+    sources.filter_map do |src|
+      basename = File.basename(src, ".md")
+      # Codex advisor support is out of scope for this release (intent 185): the
+      # owner has not evaluated the Codex reasoning-model ecosystem long enough to
+      # judge it. Skip every AgentModels::CONSULTATION_AGENTS file (both
+      # plastic-advisor and plastic-faux-advisor) by name, a deliberate and
+      # mechanical scope cut tracked at intent 186 (Codex advisor evaluation), not
+      # a permanent exclusion and not conditioned on any frontmatter or override
+      # value.
+      next if AgentModels::CONSULTATION_AGENTS.include?(basename)
+
+      dest = File.join(agents_root, "#{basename}.toml")
+      write_text_atomic(dest, render_codex_agent_toml(src, models[basename]))
+      dest
+    end
+  end
+
+  # Render one repo agents/*.md into a deterministic Codex agent TOML document. Fixed field
+  # order (name, description, one model field, developer_instructions) so regenerate is
+  # byte-identical (idempotency).
+  def render_codex_agent_toml(source_path, override)
+    front, body = split_frontmatter(File.read(source_path))
+    name = (front["name"] || File.basename(source_path, ".md")).to_s
+    description = (front["description"] || "").to_s
+    effective = (override && !override.to_s.empty? ? override : front["model"]).to_s
+
+    parts = []
+    parts << %(name = "#{toml_inline_escape(name)}")
+    parts << %(description = "#{toml_inline_escape(description)}")
+    parts << codex_model_fields(effective)
+    parts << "developer_instructions = \"\"\"\n#{toml_ml_escape(body.strip)}\n\"\"\""
+    parts.reject(&:empty?).join("\n") + "\n"
+  end
+
+  # Split a Plastic agent .md into [frontmatter_hash, body]. Tolerant: a file with no
+  # frontmatter yields [{}, whole content].
+  def split_frontmatter(content)
+    if content =~ /\A---\s*\n(.*?)\n---\s*\n?(.*)\z/m
+      front = YAML.safe_load($1) rescue {}
+      front = {} unless front.is_a?(Hash)
+      [front, $2]
+    else
+      [{}, content]
+    end
+  end
+
+  # The single model-selection line. A known tier alias (opus/sonnet/haiku) emits
+  # model_reasoning_effort only; any other non-empty value is a literal Codex model id
+  # emitted verbatim as `model`. Empty -> no line (the agent inherits the session default).
+  def codex_model_fields(effective)
+    return "" if effective.nil? || effective.to_s.empty?
+    effort = AgentModels.effort_for(effective)
+    if effort
+      %(model_reasoning_effort = "#{effort}")
+    else
+      %(model = "#{toml_inline_escape(effective.to_s)}")
+    end
+  end
+
+  # Escape arbitrary text for a TOML multi-line basic string ("""..."""). Order matters:
+  # normalize line endings, escape backslash FIRST (so introduced escapes are not
+  # re-escaped), then EVERY double-quote (which alone prevents any triple-quote delimiter
+  # collision), then C0 control chars other than tab/newline.
+  def toml_ml_escape(str)
+    s = str.to_s.gsub(/\r\n?/, "\n")
+    s = s.gsub("\\") { "\\\\" }
+    s = s.gsub('"') { '\\"' }
+    s.gsub(/[\x00-\x08\x0b\x0c\x0e-\x1f]/) { |c| format('\u%04X', c.ord) }
+  end
+
+  # Escape text for a single-line TOML basic string ("..."). Collapse any newline to a
+  # space (single-line context), then the same backslash/quote/control escapes.
+  def toml_inline_escape(str)
+    s = str.to_s.gsub(/\s*\r?\n\s*/, " ").strip
+    s = s.gsub("\\") { "\\\\" }
+    s = s.gsub('"') { '\\"' }
+    s.gsub(/[\x00-\x08\x0b\x0c\x0e-\x1f]/) { |c| format('\u%04X', c.ord) }
+  end
+
+  def codex_dispatcher_path
+    File.join(plastic_home, "scripts", "codex-hook")
+  end
+
+  # ~/.codex/hooks.json merge (intent 102). Guide-settled shape [guide Part 3]:
+  # top-level {"hooks": {<Event>: [...]}}, identical to Claude's settings.json
+  # hooks shape, so this mirrors merge_claude_hooks against a different file and
+  # a different purge predicate (the dispatcher command contains "codex-hook",
+  # not the "plastic-" substring merge_claude_hooks matches, since the path is
+  # "~/.plastic/scripts/codex-hook", not "~/.claude/hooks/plastic-<name>").
+  def merge_codex_hooks(hooks_json_path)
+    data = read_json_safe(hooks_json_path) || {}
+    hooks = data["hooks"] ||= {}
+    purge_stale_codex_hooks(hooks)
+    plastic = HookRegistry.codex_hooks_json(dispatcher_path: codex_dispatcher_path)
+    plastic.each do |event, groups|
+      hooks[event] ||= []
+      Array(groups).each { |g| hooks[event] << g }
+    end
+    write_json_atomic(hooks_json_path, data)
+  end
+
+  def purge_stale_codex_hooks(hooks)
+    codex_cmd = ->(cmd) { cmd.to_s.include?("codex-hook") }
+
+    hooks.each do |event, groups|
+      next unless groups.is_a?(Array)
+
+      hooks[event] = groups.map do |group|
+        if group.is_a?(Hash) && group["hooks"].is_a?(Array)
+          group["hooks"].reject! { |h| codex_cmd.call(h["command"]) }
+          group unless group["hooks"].empty?
+        elsif group.is_a?(Hash) && group["command"]
+          codex_cmd.call(group["command"]) ? nil : group
+        else
+          group
+        end
+      end.compact
+    end
+  end
+
   def install_hermes(config, force)
     installed = []
     skills_source = File.join(package_root, "skills")
-    installed += install_skills_flat(skills_source, File.join(config[:dir], "skills")) if File.directory?(skills_source)
-    installed += install_agents(File.join(config[:dir], "agents"), models: agent_model_overrides)
+    skill_exclude = advisor_enabled? ? [] : ["agent-advisor"]
+    installed += install_skills_flat(skills_source, File.join(config[:dir], "skills"), exclude: skill_exclude) if File.directory?(skills_source)
+    installed += install_agents(File.join(config[:dir], "agents"), models: agent_model_overrides, advisor_enabled: advisor_enabled?)
 
     write_manifest(installed, File.join(config[:dir], "plastic-manifest.json"))
     { agent: config[:name], success: true, files: installed.size }
@@ -485,12 +668,14 @@ class InstallerCore
   # directory name -- the only personal-skill namespacing Claude Code supports).
   # Any top-level underscore-prefixed markdown fragment (e.g. `_active-intent-gate.md`,
   # `_decision-tables.md`) is a shared non-skill fragment and relocates to ~/.plastic/
-  # instead, so every skill can read it from one shared location.
-  def install_skills_flat(skills_source, skills_root)
+  # instead, so every skill can read it from one shared location. `exclude` skips
+  # named top-level skill directories entirely (intent 185: the agent-advisor skill
+  # when advisor.enabled is false).
+  def install_skills_flat(skills_source, skills_root, exclude: [])
     installed = []
     FileUtils.mkdir_p(skills_root)
 
-    Dir.children(skills_source).reject { |e| e.start_with?(".") }.each do |entry|
+    Dir.children(skills_source).reject { |e| e.start_with?(".") || exclude.include?(e) }.each do |entry|
       src = File.join(skills_source, entry)
       if File.directory?(src)
         installed += copy_dir_recursive(src, File.join(skills_root, "plastic-#{entry}"))
@@ -510,10 +695,18 @@ class InstallerCore
   # equivalents). Returns the installed destination paths so callers can append
   # them to `installed` before write_manifest (manifest + prune are then automatic).
   # No-op safe: returns [] when the package has no agents dir or it is empty.
-  def install_agents(agents_root, models: {})
+  # advisor_enabled: false (advisor.enabled config key) skips every
+  # AgentModels::CONSULTATION_AGENTS file entirely (both plastic-advisor and
+  # plastic-faux-advisor), so a user who declined the advisor never gets either
+  # agent installed.
+  def install_agents(agents_root, models: {}, advisor_enabled: true)
     sources = Dir.glob(File.join(package_root, "agents", "*.md"))
     return [] if sources.empty?
 
+    unless advisor_enabled
+      sources = sources.reject { |src| AgentModels::CONSULTATION_AGENTS.include?(File.basename(src, ".md")) }
+    end
+
     FileUtils.mkdir_p(agents_root)
     sources.map do |src|
       dest = File.join(agents_root, File.basename(src))
@@ -535,9 +728,18 @@ class InstallerCore
   end
 
   # Resolve per-agent model overrides for this install: project config (when a
-  # project dir is known) overlaid on global config. Defaults are NOT included,
-  # so unconfigured agents keep their shipped frontmatter.
-  def agent_model_overrides(project_dir = nil)
+  # project dir is known) overlaid on global config, scoped to `harness`
+  # ("claude" or "codex"). Defaults are NOT included, so unconfigured agents
+  # keep their shipped frontmatter.
+  #
+  # Both advisor agents (plastic-advisor, plastic-faux-advisor) resolve through
+  # this SAME generic map, like any other agent: a config author sets
+  # agents.models.claude.plastic-advisor (or the legacy flat
+  # agents.models.plastic-advisor, read as claude) to point either agent at a
+  # different literal model. There is no separate advisor-specific model key;
+  # which agent the advisor SKILL routes to by default is a routing decision
+  # (advisor.claude.default), never a model-selection one.
+  def agent_model_overrides(project_dir = nil, harness: "claude")
     global_config = load_config_yaml(File.join(plastic_home, "config.yml"))
     project_config =
       if project_dir
@@ -545,7 +747,54 @@ class InstallerCore
       else
         {}
       end
-    AgentModels.override_map(project_config: project_config, global_config: global_config)
+    AgentModels.override_map(project_config: project_config, global_config: global_config, harness: harness)
+  end
+
+  # advisor.enabled: project overlays global, missing or malformed counts as
+  # enabled (fail-open). Harness-blind: false skips both advisor agents and the
+  # agent-advisor skill on every installed harness.
+  def advisor_enabled?(project_dir = nil)
+    global_config = load_config_yaml(File.join(plastic_home, "config.yml"))
+    project_config = project_dir ? load_config_yaml(File.join(project_dir, ".plastic_store", "config.yml")) : {}
+    value = project_config.dig("advisor", "enabled")
+    value = global_config.dig("advisor", "enabled") if value.nil?
+    value != false
+  end
+
+  # Agent-name shorthands for the --advisor flag: the two shipped choices,
+  # named for the role (real advisor vs. the cheaper imitation), never a model
+  # name.
+  ADVISOR_SHORTHANDS = { "real" => "plastic-advisor", "faux" => "plastic-faux-advisor" }.freeze
+
+  # Write advisor.enabled / advisor.claude.default into the global config.yml
+  # from install-time flags. Absent flags change nothing: advisor.enabled
+  # defaults to enabled when missing, and advisor.claude.default is left unset
+  # (the skill's own fallback chain applies) when missing.
+  #   --no-advisor      -> advisor.enabled: false
+  #   --advisor VALUE   -> advisor.claude.default: VALUE (an agent name, or the
+  #                        shorthand "real"/"faux")
+  def apply_config_flags(argv)
+    no_advisor = argv.include?("--no-advisor")
+    advisor_idx = argv.index("--advisor")
+    advisor_value = advisor_idx && argv[advisor_idx + 1]
+    return unless no_advisor || advisor_value
+
+    config_path = File.join(plastic_home, "config.yml")
+    config = load_config_yaml(config_path)
+
+    if no_advisor
+      config["advisor"] ||= {}
+      config["advisor"]["enabled"] = false
+    end
+    if advisor_value
+      agent_name = ADVISOR_SHORTHANDS[advisor_value] || advisor_value
+      config["advisor"] ||= {}
+      config["advisor"]["claude"] ||= {}
+      config["advisor"]["claude"]["default"] = agent_name
+    end
+
+    FileUtils.mkdir_p(plastic_home)
+    File.write(config_path, YAML.dump(config))
   end
 
   def load_config_yaml(path)
@@ -691,6 +940,77 @@ class InstallerCore
     end
   end
 
+  # --- Codex AGENTS.md marked-section injection (22a/Beads pattern) ---
+  # New primitive: markdown marked-section merge, the analog of merge_claude_hooks'
+  # JSON read-modify-write for a partial-ownership text file. Three states
+  # (create/append/replace), a body freshness hash in the BEGIN marker, atomic
+  # writes, and the 22a safety rule: never write when the existing section can't
+  # be parsed (a BEGIN marker with no matching END).
+
+  # Atomic text writer, mirrors write_json_atomic.
+  def write_text_atomic(path, content)
+    tmp = "#{path}.plastic-tmp.#{Process.pid}"
+    File.write(tmp, content)
+    File.rename(tmp, path)
+  rescue => e
+    File.delete(tmp) if tmp && File.exist?(tmp)
+    raise e
+  end
+
+  def codex_section(body: CODEX_AGENTS_MD_BODY)
+    hash = Digest::SHA256.hexdigest(body)[0, 12]
+    "#{CODEX_SECTION_BEGIN_PREFIX} hash:#{hash} -->\n#{body.strip}\n#{CODEX_SECTION_END}\n"
+  end
+
+  # Returns :created / :appended / :replaced / :refused. Never raises on a normal user file.
+  def inject_codex_agents_md(path, body: CODEX_AGENTS_MD_BODY)
+    section = codex_section(body: body)
+
+    unless File.exist?(path)
+      FileUtils.mkdir_p(File.dirname(path))
+      write_text_atomic(path, section)
+      return :created
+    end
+
+    content = File.read(path)
+    has_begin = content.include?(CODEX_SECTION_BEGIN_PREFIX)
+    has_end = content.include?(CODEX_SECTION_END)
+
+    # 22a safety rule: never write if the existing section cannot be parsed.
+    return :refused if has_begin && !has_end
+
+    if has_begin
+      write_text_atomic(path, content.sub(CODEX_SECTION_RE, section))
+      :replaced
+    else
+      base = content.end_with?("\n") ? content : content + "\n"
+      write_text_atomic(path, base + "\n" + section)
+      :appended
+    end
+  end
+
+  # Remove exactly Plastic's managed section from a user-owned AGENTS.md. Preserve all other
+  # content. Delete the file only if Plastic created it and nothing else remains. Returns the
+  # path when it acted, nil on no-op. Mirrors remove_claude_hooks: dedicated surgical strip,
+  # never the manifest whole-file-delete path.
+  def strip_codex_section(path)
+    return nil unless File.exist?(path)
+    content = File.read(path)
+    return nil unless content.include?(CODEX_SECTION_BEGIN_PREFIX)
+
+    # Remove the section plus the single separator newline the append introduced, so a
+    # standard user file round-trips byte-identical.
+    stripped = content.sub(/\n?#{CODEX_SECTION_RE}/, "")
+
+    if stripped.strip.empty?
+      File.delete(path)                 # Plastic-created file: nothing else left
+    else
+      stripped = stripped.rstrip + "\n" # normalize trailing whitespace we may have left
+      write_text_atomic(path, stripped)
+    end
+    path
+  end
+
   # --- Uninstall ---
 
   def handle_uninstall(uninstall_agents)
@@ -765,6 +1085,19 @@ class InstallerCore
       removed.concat(migrate_legacy_plugin(config[:dir]))
     end
 
+    # Codex: surgically strip Plastic's marked section from the user-owned AGENTS.md
+    # (dedicated pair, never the manifest whole-file-delete path above), plus the
+    # Plastic entries from hooks.json (intent 102).
+    if key == "codex"
+      agents_md = File.join(config[:home_dir], "AGENTS.md")
+      stripped = strip_codex_section(agents_md)
+      removed << stripped if stripped
+
+      hooks_json = File.join(config[:home_dir], "hooks.json")
+      hooks_removed = remove_codex_hooks(hooks_json)
+      removed << hooks_removed if hooks_removed
+    end
+
     { success: true, files: removed.size, removed: removed }
   end
 
@@ -807,6 +1140,38 @@ class InstallerCore
     write_json_atomic(settings_path, settings)
   end
 
+  # Remove exactly Plastic's entries from ~/.codex/hooks.json (intent 102), mirrors
+  # remove_claude_hooks against the Codex file/purge predicate. Returns the path
+  # when it acted (rewritten or deleted), nil on no-op, mirroring strip_codex_section's
+  # convention so the caller only records an actual change.
+  def remove_codex_hooks(hooks_json_path)
+    data = read_json_safe(hooks_json_path)
+    return nil unless data && data["hooks"]
+
+    before = JSON.generate(data)
+
+    data["hooks"].each do |event, groups|
+      next unless groups.is_a?(Array)
+
+      data["hooks"][event] = groups.map do |g|
+        next g unless g.is_a?(Hash) && Array(g["hooks"]).is_a?(Array)
+
+        g["hooks"] = Array(g["hooks"]).reject { |h| h["command"].to_s.include?("codex-hook") }
+        g["hooks"].empty? ? nil : g
+      end.compact
+    end
+    data["hooks"].delete_if { |_, v| v.is_a?(Array) && v.empty? }
+
+    return nil if JSON.generate(data) == before # nothing to change: true no-op
+
+    if data["hooks"].empty? && data.keys == ["hooks"]
+      File.delete(hooks_json_path) # Plastic-created and now empty: remove
+    else
+      write_json_atomic(hooks_json_path, data)
+    end
+    hooks_json_path
+  end
+
   # --- Utilities ---
 
   def agent_config(key)

package/skills/agent-advisor/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: plastic-agent-advisor
+description: >-
+  Consult the advisor for expensive reasoning: one-way doors, plans, adversarial
+  review of a plan or conclusion before an irreversible step, a deadlock after two
+  failed attempts, or ranking several plausible options. Use when the user asks for
+  a second opinion, a hard design decision, an architecture review, help breaking a
+  deadlock, or says "ask the advisor". Also sets which advisor is the default when
+  asked ("make Fable my advisor", "switch my advisor", "use the real advisor").
+user-invocable: true
+---
+
+# Agent Advisor
+
+Plastic ships two consultation agents, never dispatched by the auto pipeline, summoned
+only when you decide the reasoning is worth buying:
+
+- **`plastic-advisor`** ("the real advisor"): the frontier model itself, expensive,
+  billed through usage credits. Spawn it for a few rounds on the hardest problem, then
+  close the session.
+- **`plastic-faux-advisor`** ("the imitation advisor"): an ordinary model carrying the
+  same reasoning discipline inline in its own body, so it reasons the same disciplined
+  way at a fraction of the cost. The cheaper default.
+
+## When to consult (and when not to)
+
+Buy a consultation for: decisions with one-way doors (architecture, migration order,
+public contracts); turning a goal plus evidence into a step plan with checks;
+adversarial review of your plan or conclusion before an irreversible step; a deadlock
+after two failed attempts where you cannot say why; ranking several plausible options
+when the ordering decides where you spend the next day.
+
+Never buy a consultation for: anything a tool can answer (search, reading code, running
+tests, documentation), writing code at volume, confirming a decision you already made,
+style or naming a linter would settle, or anything reversible and cheap you have not
+tried first. The full buy/never-buy list, the tier table, and the entry test live in
+`references/advisor-protocol.md`; read it before writing a brief for the first time in
+a session.
+
+## Routing: which advisor answers
+
+1. Read the harness-scoped config: `advisor.claude.default`. If unset, fall back to
+   `advisor.claude.secondary`, then to `plastic-faux-advisor`.
+2. If the user names which advisor they want ("ask the real one", "use Fable", "ask the
+   cheap one"), honor that directly and dispatch `advisor.claude.primary` (default
+   `plastic-advisor`) or `advisor.claude.secondary` (default `plastic-faux-advisor`)
+   accordingly, overriding step 1 for this consultation only.
+3. If `advisor.enabled` reads `false`, neither advisor agent nor this skill is
+   installed; this step should not be reachable, but if it is, tell the user the
+   advisor is disabled and point at "Setting the default" below.
+4. Dispatch the resolved agent with a brief built per `references/advisor-protocol.md`
+   section 4 (natural prose, the block is a completeness check, not a form to fill).
+   State TIER (S, M, or L) and EFFORT explicitly; classify low and prove your way up,
+   never open high "to be safe".
+5. Consume the answer per the protocol's section 5: run the Operating Manual's
+   five-question self-test on the advisor's plan before executing it. Advice is input,
+   not authority; the plan is the advisor's, the outcome is yours.
+
+Read the resolved config value with:
+
+```bash
+ruby ~/.plastic/scripts/read-config advisor.claude.default --project <repo>
+```
+
+(Omit `--project` outside a registered project; falls back to the global value.)
+
+## Setting the default advisor
+
+When asked to change the default ("make Fable my advisor", "switch my advisor", "use
+the cheaper one by default"), present the two options in plain language and write the
+choice:
+
+- **Faux Fable** (`plastic-faux-advisor`, recommended): an ordinary model carrying the
+  frontier reasoning instructions. Much cheaper, available on any plan, reasons in the
+  same disciplined way.
+- **Fable 5** (`plastic-advisor`): the frontier model itself. The strongest reasoning
+  available, billed through usage credits, so summon it for a few rounds and close it.
+
+These are the same two options the installer offers at install and update time. Write
+the choice to `advisor.claude.default` in the global `~/.plastic/config.yml` (or the
+project's `.plastic_store/config.yml` when the user scopes the change to one project):
+read the file as YAML, set `advisor.claude.default` to the agent name (`plastic-advisor`
+or `plastic-faux-advisor`, never a model name or nickname), and write it back. Confirm
+the new default back to the user in one line.
+
+## References
+
+- `references/advisor-protocol.md`: the full shipped Advisor Protocol (what to buy,
+  tiers and effort, the entry test, how to write a brief that earns its cost, the
+  answer contract, session economics, anti-patterns). Read it before the first
+  consultation in a session; the second consultation in the same advisor thread costs a
+  fraction of the first, so keep follow-ups on one thread rather than opening a new one.