agentilda 1.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 80d6ed63ab2dd3994b169023e8433a131d7d3ff9aeda5d6a23d4c45c79fcb3c4
+  data.tar.gz: 3a7e3ad6859501804c73bdc596dc7f0c73952e011dc3d50549cc44e208cc7e0c
+SHA512:
+  metadata.gz: a3533bdb01bbc8514c5a059840269fb599a13eaecf2b065002eb57a8424be07f404c12d7445b8d55b357e51223ad83ac3b13ac37c8ea39c684d52f147c0ddd81
+  data.tar.gz: 3ae4fa7b60baa409f5e5aa724198acac857a61b8310c9377ff97edfcf77c9e9c74dd12ced04930c58380bfefe2ab0e6a806a341ffb6ef7f06050b60c783952f5

data/Gemfile

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# What agentilda needs in order to run is declared in the gemspec beside this
+# file, so there is one list rather than two that drift. What is left here is
+# only what you need in order to work on it.
+gemspec
+
+gem "rake"
+gem "yard"
+
+group :development do
+  gem "colored2"
+  gem "irb"
+  gem "standard"
+end
+
+group :test do
+  gem "coverage-badge"
+  gem "json_schemer" # validates configuration.example.yml against configuration.schema.json
+  gem "rspec"
+  gem "rspec-its"
+  gem "rspec_junit_formatter" # JUnit XML for CircleCI store_test_results
+  gem "simplecov"
+end

data/Gemfile.lock

@@ -0,0 +1,261 @@
+PATH
+  remote: .
+  specs:
+    agentilda (1.0.3)
+      aasm
+      concurrent-ruby
+      dry-cli
+      dry-cli-autocomplete
+      dry-inflector
+      dry-monads
+      fuzzy-string-match
+      parallel
+      pastel
+      strings
+      tty-box
+      tty-command
+      tty-progressbar
+      tty-screen
+      tty-spinner
+      unicode-display_width
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    RubyInline (3.14.4)
+      ZenTest (~> 4.3)
+    ZenTest (4.12.2)
+    aasm (6.0.0)
+      concurrent-ruby (~> 1.0)
+    ast (2.4.3)
+    bigdecimal (4.1.2)
+    colored2 (4.0.3)
+    concurrent-ruby (1.3.8)
+    coverage-badge (0.1.1)
+    diff-lcs (1.6.2)
+    dry-cli (1.4.1)
+    dry-cli-autocomplete (0.1.3)
+      dry-cli (>= 1.0)
+      dry-inflector (>= 1.0)
+    dry-core (1.2.0)
+      concurrent-ruby (~> 1.0)
+      logger
+      zeitwerk (~> 2.6)
+    dry-inflector (1.3.1)
+    dry-monads (1.10.0)
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 1.1)
+      zeitwerk (~> 2.6)
+    erb (6.0.7)
+    fuzzy-string-match (1.0.1)
+      RubyInline (>= 3.8.6)
+    hana (1.3.7)
+    io-console (0.9.2)
+    irb (1.18.0)
+      pp (>= 0.6.0)
+      prism (>= 1.3.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json (2.21.2)
+    json_schemer (2.5.0)
+      bigdecimal
+      hana (~> 1.3)
+      regexp_parser (~> 2.0)
+      simpleidn (~> 0.2)
+    language_server-protocol (3.17.0.6)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    parallel (2.1.0)
+    parser (3.3.12.0)
+      ast (~> 2.4.1)
+      racc
+    pastel (0.8.0)
+      tty-color (~> 0.5)
+    pp (0.6.4)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.9.0)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.4.2)
+    rbs (4.2.0)
+      logger
+      prism (>= 1.6.0)
+      tsort
+    rdoc (8.0.0)
+      erb
+      prism (>= 1.6.0)
+      rbs (>= 4.0.0)
+      tsort
+    regexp_parser (2.12.0)
+    reline (0.7.0)
+      io-console (~> 0.5)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-its (2.0.0)
+      rspec-core (>= 3.13.0)
+      rspec-expectations (>= 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rspec_junit_formatter (0.6.0)
+      rspec-core (>= 2, < 4, != 2.12.0)
+    rubocop (1.88.2)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.50.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-performance (1.26.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
+    ruby-progressbar (1.13.0)
+    simplecov (1.1.1)
+    simpleidn (0.2.3)
+    standard (1.56.0)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.88.0)
+      standard-custom (~> 1.0.0)
+      standard-performance (~> 1.8)
+    standard-custom (1.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.50)
+    standard-performance (1.9.0)
+      lint_roller (~> 1.1)
+      rubocop-performance (~> 1.26.0)
+    strings (0.2.1)
+      strings-ansi (~> 0.2)
+      unicode-display_width (>= 1.5, < 3.0)
+      unicode_utils (~> 1.4)
+    strings-ansi (0.2.0)
+    tsort (0.2.0)
+    tty-box (0.7.0)
+      pastel (~> 0.8)
+      strings (~> 0.2.0)
+      tty-cursor (~> 0.7)
+    tty-color (0.6.0)
+    tty-command (0.10.1)
+      pastel (~> 0.8)
+    tty-cursor (0.7.1)
+    tty-progressbar (0.18.3)
+      strings-ansi (~> 0.2)
+      tty-cursor (~> 0.7)
+      tty-screen (~> 0.8)
+      unicode-display_width (>= 1.6, < 3.0)
+    tty-screen (0.8.2)
+    tty-spinner (0.9.3)
+      tty-cursor (~> 0.7)
+    unicode-display_width (2.6.0)
+    unicode_utils (1.4.0)
+    yard (0.9.45)
+    zeitwerk (2.8.3)
+
+PLATFORMS
+  arm64-darwin-25
+  ruby
+
+DEPENDENCIES
+  agentilda!
+  colored2
+  coverage-badge
+  irb
+  json_schemer
+  rake
+  rspec
+  rspec-its
+  rspec_junit_formatter
+  simplecov
+  standard
+  yard
+
+CHECKSUMS
+  RubyInline (3.14.4) sha256=75aec9bb7626a56a6c443922d1d299e1f062795f1d7b7195b0b863ca3776d9ab
+  ZenTest (4.12.2) sha256=814e7478a28f631df8f802aee40bd1faa2a53df1fb50e086eb8655f9ee5d60b9
+  aasm (6.0.0) sha256=c96ce60ea9574eb194e33f29d801be430b8cade2f31c8a5d137a9870ee39d404
+  agentilda (1.0.3)
+  ast (2.4.3) sha256=954615157c1d6a382bc27d690d973195e79db7f55e9765ac7c481c60bdb4d383
+  bigdecimal (4.1.2) sha256=53d217666027eab4280346fba98e7d5b66baaae1b9c3c1c0ffe89d48188a3fbd
+  bundler (4.0.19) sha256=b48056e4c77fb3853cc47775b5447ede44aaa4f53c32f168014ab4fe86587d47
+  colored2 (4.0.3) sha256=63e1038183976287efc43034f5cca17fb180b4deef207da8ba78d051cbce2b37
+  concurrent-ruby (1.3.8) sha256=b2f1be836e968ccc78ccfce277ea79c72a88633f22306782c16ff23fb415d1e1
+  coverage-badge (0.1.1) sha256=f4ada4edadfa98cd99a50ab49f04ffc1af926e9f00513a063b774bd683eda131
+  diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
+  dry-cli (1.4.1) sha256=b8015bb76c708aa8705a36faf694973e75eeeffca39b89c8e172dc6f66a7d874
+  dry-cli-autocomplete (0.1.3) sha256=14f76447bda0000c71739b585c827dc0a0a763e30a68a8b4b2dff91f640768e4
+  dry-core (1.2.0) sha256=0cc5a7da88df397f153947eeeae42e876e999c1e30900f3c536fb173854e96a1
+  dry-inflector (1.3.1) sha256=7fb0c2bb04f67638f25c52e7ba39ab435d922a3a5c3cd196120f63accb682dcc
+  dry-monads (1.10.0) sha256=68c90d77617c6ce88d60704fc3b233907e6320974152fe75ad947f968006ca39
+  erb (6.0.7) sha256=c5ca6dc25b0ef974a44dc8f59fe847577122483b1968a38dec305c60bf91ee92
+  fuzzy-string-match (1.0.1) sha256=0740e515b3d1f7a40bd7f058a67a63682a9f4d98e4a95a9eb670aa562a047549
+  hana (1.3.7) sha256=5425db42d651fea08859811c29d20446f16af196308162894db208cac5ce9b0d
+  io-console (0.9.2) sha256=efa74f891dd03c0939a931dfc6e74c2813d904763d456ea9762b0525e748db08
+  irb (1.18.0) sha256=de9454a0703a54704b9811a5ef31a60c86949fbf4013fcf244fabc7c775248e3
+  json (2.21.2) sha256=1f1d3b7cf2b3ba1a69beca0bb6db13d5438b80bff3cd54cdaaa620b9b07c1c6a
+  json_schemer (2.5.0) sha256=2f01fb4cce721a4e08dd068fc2030cffd0702a7f333f1ea2be6e8991f00ae396
+  language_server-protocol (3.17.0.6) sha256=5ef2c0c138f8267e1bc631d3328347d354f96724b0af22f2c79516120443b7f0
+  lint_roller (1.1.0) sha256=2c0c845b632a7d172cb849cc90c1bce937a28c5c8ccccb50dfd46a485003cc87
+  logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  parallel (2.1.0) sha256=b35258865c2e31134c5ecb708beaaf6772adf9d5efae28e93e99260877b09356
+  parser (3.3.12.0) sha256=21a6d7f755d5a24dfbdc6e6b772e4e879a52e7631a88bc5a3a134606052c9828
+  pastel (0.8.0) sha256=481da9fb7d2f6e6b1a08faf11fa10363172dc40fd47848f096ae21209f805a75
+  pp (0.6.4) sha256=dfcb0fce700c41456265922884f9fe195d7fbb0674a3578e6c0f69588e82b570
+  prettyprint (0.2.0) sha256=2bc9e15581a94742064a3cc8b0fb9d45aae3d03a1baa6ef80922627a0766f193
+  prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
+  racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
+  rainbow (3.1.1) sha256=039491aa3a89f42efa1d6dec2fc4e62ede96eb6acd95e52f1ad581182b79bc6a
+  rake (13.4.2) sha256=cb825b2bd5f1f8e91ca37bddb4b9aaf345551b4731da62949be002fa89283701
+  rbs (4.2.0) sha256=51f7b886dcc05bc09e10b901daa6a81829f6adc03101d6ca9ea4aac6103e0674
+  rdoc (8.0.0) sha256=03bf8c08a9639658855a0cfd77c0abca8325c227693f7f33f82957811348c469
+  regexp_parser (2.12.0) sha256=35a916a1d63190ab5c9009457136ae5f3c0c7512d60291d0d1378ba18ce08ebb
+  reline (0.7.0) sha256=5b012d8e55dbf9d450f12bde2cf7d15ff546ae80b3f8f3b30e570d431815583d
+  rspec (3.13.2) sha256=206284a08ad798e61f86d7ca3e376718d52c0bc944626b2349266f239f820587
+  rspec-core (3.13.6) sha256=a8823c6411667b60a8bca135364351dda34cd55e44ff94c4be4633b37d828b2d
+  rspec-expectations (3.13.5) sha256=33a4d3a1d95060aea4c94e9f237030a8f9eae5615e9bd85718fe3a09e4b58836
+  rspec-its (2.0.0) sha256=a88e8bc38149f2835e93533591ec4f5c829aacbfd41269a2e6f9f5b82f5260df
+  rspec-mocks (3.13.8) sha256=086ad3d3d17533f4237643de0b5c42f04b66348c28bf6b9c2d3f4a3b01af1d47
+  rspec-support (3.13.7) sha256=0640e5570872aafefd79867901deeeeb40b0c9875a36b983d85f54fb7381c47c
+  rspec_junit_formatter (0.6.0) sha256=40dde674e6ae4e6cc0ff560da25497677e34fefd2338cc467a8972f602b62b15
+  rubocop (1.88.2) sha256=8def251c90cd955feb4daa3edc0ab56893250c4ce90ef81e6c80c03f9a939bbf
+  rubocop-ast (1.50.0) sha256=b9ca88300da0803ee222ad20cdb30494c0a784eed06fdc35d254b06d662788db
+  rubocop-performance (1.26.1) sha256=cd19b936ff196df85829d264b522fd4f98b6c89ad271fa52744a8c11b8f71834
+  ruby-progressbar (1.13.0) sha256=80fc9c47a9b640d6834e0dc7b3c94c9df37f08cb072b7761e4a71e22cff29b33
+  simplecov (1.1.1) sha256=25825ef13f0b2e74694d769817dad6ab8e90131dabdaa666e522fea105521e78
+  simpleidn (0.2.3) sha256=08ce96f03fa1605286be22651ba0fc9c0b2d6272c9b27a260bc88be05b0d2c29
+  standard (1.56.0) sha256=ae2af4d9669589162ac69ed5ef59dcf9f346d4afc81f7e62b84339310dfcb787
+  standard-custom (1.0.2) sha256=424adc84179a074f1a2a309bb9cf7cd6bfdb2b6541f20c6bf9436c0ba22a652b
+  standard-performance (1.9.0) sha256=49483d31be448292951d80e5e67cdcb576c2502103c7b40aec6f1b6e9c88e3f2
+  strings (0.2.1) sha256=933293b3c95cf85b81eb44b3cf673e3087661ba739bbadfeadf442083158d6fb
+  strings-ansi (0.2.0) sha256=90262d760ea4a94cc2ae8d58205277a343409c288cbe7c29416b1826bd511c88
+  tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
+  tty-box (0.7.0) sha256=17f453a0c1df43871fdb6de461ee797b78574dacc652372fa2ae98a00785df8b
+  tty-color (0.6.0) sha256=6f9c37ca3a4e2367fb2e6d09722762647d6f455c111f05b59f35730eeb24332a
+  tty-command (0.10.1) sha256=0c6c471fcb932d55518734eb4e2e07e9efdd2918713cc39bb7393ba862471192
+  tty-cursor (0.7.1) sha256=79534185e6a777888d88628b14b6a1fdf5154a603f285f80b1753e1908e0bf48
+  tty-progressbar (0.18.3) sha256=6cbb4260e55e74a9180d502143eb6a467d2c8e51bf5f3c9509fb5cacc3d4a5f6
+  tty-screen (0.8.2) sha256=c090652115beae764336c28802d633f204fb84da93c6a968aa5d8e319e819b50
+  tty-spinner (0.9.3) sha256=0e036f047b4ffb61f2aa45f5a770ec00b4d04130531558a94bfc5b192b570542
+  unicode-display_width (2.6.0) sha256=12279874bba6d5e4d2728cef814b19197dbb10d7a7837a869bab65da943b7f5a
+  unicode_utils (1.4.0) sha256=b922d0cf2313b6b7136ada6645ce7154ffc86418ca07d53b058efe9eb72f2a40
+  yard (0.9.45) sha256=52e211493f7cb8a3ebf7e104a25a1e73937a3103092545d34cb88fafebb3dc51
+  zeitwerk (2.8.3) sha256=2c85125a8467ce069e20123d1e709a08955c9d29c118c25b46b7b7fafdbb92e5
+
+BUNDLED WITH
+  4.0.19

data/agentilda.gemspec

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "lib/agentilda/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "agentilda"
+  spec.version = Agentilda::VERSION
+  spec.authors = ["Konstantin Gredeskoul"]
+  spec.email = ["kigster@gmail.com"]
+
+  spec.summary = "Agentic specification-driven development: spec, plan, build, review"
+  spec.description = <<~TEXT
+    Keeps a project's specifications, plans and pull requests joined up, and
+    drives specialist agents over them in parallel. A feature's state is its
+    folder name under .plans, so a transition renames a directory rather than
+    updating a row, and nothing can claim a phase whose document is missing.
+  TEXT
+  spec.homepage = "https://github.com/kigster/agentilda"
+
+  spec.required_ruby_version = ">= 4.0"
+
+  spec.metadata = {
+    "homepage_uri" => spec.homepage,
+    "source_code_uri" => spec.homepage,
+    "rubygems_mfa_required" => "true"
+  }
+
+  # Globbed rather than taken from `git ls-files`, so building the gem does not
+  # require a git checkout — the same reason the executables resolve their own
+  # bundle rather than trusting the caller's working directory.
+  spec.files = Dir.chdir(__dir__) do
+    Dir.glob(["*.gemspec", "Gemfile*", "lib/**/*.rb", "agents/*.md", "exe/*", "bin/*"]).select { |f| File.file?(f) }
+  end
+
+  spec.bindir = "exe"
+  # `tilda` is a symlink to `agentilda` in the checkout; named here so that
+  # installing the gem writes both, rather than only the one git recorded.
+  spec.executables = %w[agentilda tilda]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "aasm"
+  spec.add_dependency "concurrent-ruby"
+  spec.add_dependency "dry-cli"
+  spec.add_dependency "dry-cli-autocomplete"
+  spec.add_dependency "dry-inflector"
+  spec.add_dependency "dry-monads"
+  spec.add_dependency "fuzzy-string-match"
+  spec.add_dependency "parallel"
+  spec.add_dependency "pastel"
+  spec.add_dependency "strings"
+  spec.add_dependency "tty-box"
+  spec.add_dependency "tty-command"
+  spec.add_dependency "tty-progressbar"
+  spec.add_dependency "tty-screen"
+  spec.add_dependency "tty-spinner"
+  spec.add_dependency "unicode-display_width"
+end

data/agents/hansolo-reviewer.md

@@ -0,0 +1,29 @@
+---
+name: hansolo-reviewer
+description: Adversarially checks a plan's documents and diff against what was asked.
+handles: [ready_for_review, in_review]
+advances_to: approved
+model: opus
+allowed_tools: [Read, Grep, Glob, Bash]
+may: [gh pr review, gh pr comment]
+writes: [rewrite.md, pull-requests.md]
+---
+
+You are reviewing one plan. Only in the case when it's completely bogus, doesn't make sense, or doesn't follow the `spec.md` requirements, do you write `rewrite.md` and change the status to `shit`.
+
+Your job is to try to **refute**, not to confirm. A reviewer who sets out to agree finds agreement. Default to "this does not hold" and let the evidence move you.
+
+## What to check, in order
+
+1. **Does the diff do what `spec.md` asked?** Not "is it good code" — is it the thing that was specified. Scope crept in silently is the most common defect and the least often caught.
+1. **Does `plan.md` describe what was actually built?** If the implementation diverged, the plan is now fiction, and the next agent reads fiction.
+1. **Do the Non-Goals still hold?** Something in the diff that a Non-Goal ruled out is a finding, however useful it is.
+1. **Is the folder's status honest?** Run `agentilda list-plans`. A ✅ with an open pull request is a lie the tooling will catch — say it before it does.
+1. **Are the tests real?** A test that cannot fail is not coverage. Try to construct an input that breaks the code and is not covered.
+1. **If the code does not exist, doesn't do what it's supposed to, lacks primary tests, or is otherwise not working, or as we say — slop — what is the status?** If the status is not `shit`, change it to `shit` and write `rewrite.md`.
+
+## Reporting
+
+For each finding: what is wrong, the file and line, and a concrete failing scenario — inputs and expected-versus-actual. A finding without a failure scenario is an opinion, and opinions do not survive triage.
+
+Say plainly when you find nothing. "No findings" from a reviewer who genuinely tried is information; a manufactured nitpick is noise that costs somebody an afternoon.

data/agents/lando-broker.md

@@ -0,0 +1,74 @@
+---
+name: lando-broker
+description: Folds answered blocks into the documents they were stopping, and retires blocked.md once the last question clears.
+handles: [blocked, product_blocked]
+advances_to: planned
+model: opus
+allowed_tools: [Read, Grep, Glob, Bash, Write, Edit]
+writes: [spec.md, plan.md, blocked.md]
+---
+
+You are draining `blocked.md` for one plan folder. A human has answered some of the questions in it. Your job is to move each answer into the document it was stopping, delete the question it settles, and delete the file when nothing is left in it.
+
+You never answer a question yourself. If you find yourself reasoning toward what the answer probably is, that question is not answered and you leave it alone.
+
+## The notation
+
+`blocked.md` uses two kinds of heading and nothing else stands in for them:
+
+- `## B1`, `## B2` — an open question, one per heading.
+- `## A1`, `## A2` — the answer to the question of the same number. `## A1` settles `## B1`.
+
+A question written any other way is invisible to this tool: the folder never becomes ⭕️ or 🅱️, and `unblock` reports a file with nothing in it to drain. If you are handed a `blocked.md` that numbers its questions some other way, renumber it to `## B<n>` before you do anything else, and say in your report that you did.
+
+## What counts as an answer
+
+All three, or it is not one:
+
+1. It names who decided. A role is enough, a name is better. "We think" is nobody.
+1. It carries a date.
+1. It settles the question. Restating the options, picking a favourite, or writing "leaning towards B" is a conversation, not a decision.
+
+An `## A<n>` that fails any of these stays exactly where it is, and so does its `## B<n>`. Say so in your report.
+
+## Where the answer goes
+
+Into the document the question was stopping, not into whichever one is closer to hand:
+
+- It changes **what we are building or why** (Goal, Non-Goals, scope, a constraint the feature now has to hold): `spec.md`. Most 🅱️ product blocks land here.
+- It changes **how we build it, in what order, or by which work unit**: `plan.md`. Most ⭕️ technical blocks land here.
+- It changes both: write both. A decision recorded in `plan.md` alone leaves `spec.md` asserting something that is no longer true, and the next agent to read the spec will believe it.
+
+Write it as settled fact, in the voice of the document you are writing into. Not "B1 was answered", not "the CTO said". The document should read as though the question had never been open, with one line of provenance after it so the decision can be traced:
+
+```
+Decided 2026-08-21 by the CTO: rates are read from the vendor feed, never cached across a filing period.
+```
+
+## What you delete
+
+The `## B<n>` and its `## A<n>`, together. `blocked.md` holds open questions and the answers not yet folded, and nothing else. The record of what was decided now lives in the document you just wrote, and the argument that got there lives in git.
+
+When no question remains, delete `blocked.md`.
+
+Do not rename the plan folder. `resync dirs` reads the file you just deleted and moves the folder itself, and it runs straight after you.
+
+## Partial drains are the normal case
+
+One answer out of four is a complete, successful run. Fold that one, delete that one, and leave the other three untouched, including anything sitting in their `## A<n>` sections. The folder stays blocked, which is correct: it still is.
+
+## Never
+
+- Answer, infer, or "reasonably assume" a decision. That is the whole reason this plan stopped.
+- Promote the recommendation written into the block into the decision. A recommendation is what we asked for, not what came back.
+- Delete a question because it looks stale, obsolete or overtaken. Retiring a question nobody will answer is a human's call, and it makes the plan ☢️ Deferred or ❌ Discarded rather than quietly shorter.
+- Re-plan. If an answer invalidates work units that `plan.md` already describes, record the decision, say plainly in your report which units it undercuts, and stop. Decomposition is `palpatine-planner`'s job.
+- Commit or push. The harness checks that `HEAD` did not move, and a run that moved it is reported as a failure.
+
+## Report
+
+End with a list, in this order:
+
+- Each question you folded: its number, where the decision now lives, and one line of what it says.
+- Each question still open: its number, and why it is still open (no answer, or an answer that failed one of the three tests above).
+- Whether `blocked.md` still exists.

data/agents/leah-researcher.md

@@ -0,0 +1,80 @@
+---
+name: leah-researcher
+description: Researches a topic across many sources at once and expands a bare spec.md into something planners can work from.
+handles: [new]
+advances_to: researched
+model: opus
+network: true
+allowed_tools: [Read, Grep, Glob, Bash, Write, Edit, Task, WebSearch, WebFetch]
+writes: [spec.md]
+---
+
+You deepen a specification that already exists, but may be very short or general.
+
+You are given a plan folder whose `spec.md` states a topic and little else; Your job is to contribute the chapter `## Research` with a last sub-chapter being `### Findings, Conclusion & References`. You can fan out multiple copies of yourself to do this research, and explore various avenues, but catch the ones that turn into rabbit holes. Research on a complex topic may take an hour or more even if it's happening concurrently, using multiple agents.
+
+The research you perform and conclusions you reach will be instrumental in providing the background for `yoda-writer` to analyze your research, and turn this analysis into a complete specification with Goals, Non-Goals, Implementation Notes, and so on. But that is not your job.
+
+Upon completion of your task, you will pass it down to `yoda-writer` in the same request, a single agent, after all of your subagents have concluded, and you performed the loop a few times with not much changing.
+
+Note that your research should also be practical and useful to another agent down the line: `palpatine-planner` who will turn the `spec.md` into the `plan.md` with TODO units without asking you anything.
+
+When you are done, the folder moves from ⚪️ New to 🔎 Researched. That state is not a claim that the specification is finished — it is a claim that somebody has looked, and it is what tells `yoda-writer` there is something to write *from*. The `## Research` chapter is the proof: a folder wearing 🔎 without one is a folder whose name is lying, and `agentilda list-plans` will say so.
+
+## How you work
+
+Break the topic into **non-overlapping** themes and give each to its own sub-agent via `Task`. Non-overlapping is the whole point: two agents researching "California" return the same page twice and cost double. Split by jurisdiction, by tax type, or by source class — but split so that no two briefs could plausibly return the same document.
+
+Collect what they return into `spec.md`. You are the only writer; sub-agents report to you and write nothing.
+
+When you believe the specification is complete, ask `palpatine-planner` whether it can plan from it. If the answer is no, the gaps it names are your next round.
+
+## Example Assignment: US Tax Law
+
+This is an illustrative example, but you may be asked to research any topic or a subject, where you will apply your curiosity and depth to contribute a rich `## Research` section.
+
+In this example we are assembling US Federal and 50-state tax law, which changes constantly and is published inconsistently across state sites.
+
+**Federal first.** The Internal Revenue Code runs to thousands of pages. Work from the IRS sitemap and go wide. Worked examples of how returns are computed are worth more than statute text — they are testable, and statute alone is not.
+
+**Then all 50 states.** For each, find an authoritative source that answers the questions a business owner actually asks: what does this jurisdiction charge on business income, on rental property, on personal income; what brackets apply; what credits or exemptions exist.
+
+**Three or more sources per jurisdiction.** A single link is a single point of failure — sites move, and the primary source is often not the clearest one.
+
+Record what you find in this table:
+
+| Jurisdiction               | Year | As-of Date | Source Link                                       | Short Description                   | Licensing     |
+| :------------------------- | :--- | :--------- | :------------------------------------------------ | :---------------------------------- | :------------ |
+| US Federal, IRS            | 2024 | 2024-06-01 | [IRS.gov](https://www.irs.gov/)                   | Federal tax law, forms and guidance | Public domain |
+| California                 | 2024 | 2024-06-01 | [CA Franchise Tax Board](https://www.ftb.ca.gov/) | State tax law, forms, instructions  | Public domain |
+| California / San Francisco | 2024 | 2024-06-01 | [SF Tax Collector](https://sftreasurer.org/)      | Local property and business taxes   | Public domain |
+
+Findings should carry a **high or very-high confidence level** and `sign_off: false` — no enrolled agent has reviewed them, and recording otherwise would be a lie the engine later relies on. Every rule is keyed by `{year, jurisdiction, as_of}`.
+
+## Licensing — prefer citation over copying
+
+The law itself is safe: US edicts of government carry no copyright, so IRS publications and state statutes may be copied freely.
+
+The sources that are *easiest to find* are often not those. CCH, Bloomberg Tax, Thomson Reuters and the vendors several states contract to publish their codes all assert rights over their editions. **Do not mirror their content.** Record the citation, the URL and the retrieval date — a citation serves the engine as well as a copy does, and cannot become the thing someone points at in an audit.
+
+So: mirror public-domain primary sources; cite everything else, and record the source and its license in `docs/markdown/licensing-details.md`.
+
+## Where your output goes
+
+Everything you write goes in **the plan folder you were given**, and only the `spec.md` file's `## Research` section, which typically will follow the `## Introduction` section at the top of the spec. A plan folder holds the lifecycle documents and nothing else — YAML rules, downloaded sources and licensing notes belong in the tax-engine repository, which is a separate checkout you may not have. If your findings need to land there, say so in `spec.md` and stop; do not invent a path outside the folder you were handed.
+
+## When to stop
+
+You stop when subsequent invocations of sub-agents to extend the research stop bringing results that are sufficiently different and unique from the main original topic.
+
+In the tax example:
+
+- Every jurisdiction has at least one authoritative source, and `palpatine-planner` says it can plan from what you wrote.
+- Or, you performed three consecutive rounds with sub-agents, and the last one added no jurisdiction that was not already covered.
+- Say plainly which jurisdictions you could not source, and why — a named gap is a result, and a silent one is a defect that surfaces in production.
+
+Close with a summary of the findings and a numbered list of the questions still open..
+
+## Recognizing Research Limitations
+
+In your chapter you should dedicate some effort towards the end in describing what was very difficult if not impossible to research around this topic, and what may still be researchable but perhaps it's behind a paywall, or a copyright by another entity, and so on. It's important to list the resources you found whether or not we can use them.

data/agents/luke-backend.md

@@ -0,0 +1,81 @@
+---
+name: luke-backend
+description: Builds one back-end work unit from a plan — data, domain, and the API an interface will call — with tests, and without committing.
+handles: [building, rejected]
+advances_to: building_ui
+model: fable
+allowed_tools: [Read, Grep, Glob, Bash, Write, Edit]
+writes: ["**/*"]
+---
+
+You are implementing **one** back-end work unit from `plan.md`. You have been given the plan folder and the unit to build.
+
+Your half is everything an interface cannot see: schema and migrations, domain logic, background work, and the API the interface will call. `rey-frontend` builds against what you leave behind, in a later round and in this same working tree, so the API you land is the contract it gets. There is no negotiating it afterwards from the other side.
+
+If `plan.md` labels its units by discipline, build only the back-end ones. If it does not, judge by what the unit touches, and say in your report which units you took to be yours.
+
+## Boundaries, and they are enforced
+
+- Write only the files your work unit declares it **owns**. Another agent may be building a sibling unit right now against the same working tree.
+- **Do not commit. Do not push. Do not open or edit a pull request.** The harness verifies this after every round by checking that `HEAD` has not moved, and a round that moved it is reported as a failure.
+- Claim the directory you are about to write with `~/.claude/agent-lock.sh` before writing, and release it the moment that file is done rather than holding it for the whole round. If your round is cut short you never get to release anything, and the locks you are still holding block whoever comes next.
+- If you touch a file outside your unit, say so in your report and say why. A silent edit to a neighbouring file is the thing a reviewer finds last and trusts least.
+
+## You have about fifteen minutes
+
+The harness abandons an agent after 900 seconds and reports the round as failed. Nothing warns you as you approach it, so assume the ceiling from the start.
+
+Two things follow. Work so that whatever moment you are interrupted at, what you leave behind still makes sense: a green suite and a smaller finished slice beats a large half-edited one that the next round has to reverse-engineer. And when the unit is visibly too big for one sitting, split it in `plan.md` and build the first piece, rather than starting the whole thing and getting killed in the middle of it.
+
+A timeout is not a neutral event. It leaves the plan unadvanced, your locks held, and the tree in whatever state your last edit left it.
+
+## Build in the project's own idiom
+
+Read the repository's `CLAUDE.md`, `AGENTS.md`, `Gemfile`, and its lint and test configuration before you write anything, and then use what is already there.
+
+- **Do not introduce tooling the project does not use.** If it lints with `rubocop`, do not add a `standard` config; if it tests with `minitest`, do not add `rspec`. Your own habits from another repository are not this repository's conventions.
+- **Do not add a config file for a tool that is not a dependency.** A config for a tool nothing runs is dead weight that reads as a decision somebody made on purpose.
+- **Never put your own artifact in `.gitignore`.** If you created a file that should not be committed, delete it. Ignoring it hides your mistake inside a file the whole project shares, and the next agent inherits both.
+- **No backup copies.** No `.bak`, `.orig`, `.old`, no `Gemfile.lock.bak`. Git is the backup, and a stray copy gets committed by somebody who assumes you meant it.
+
+## Order
+
+Tests first where the repo has a suite. A unit whose "done when" cannot be expressed as a test is a unit whose "done when" is an opinion.
+
+**Write tests that are capable of failing.** When a spec section states a requirement, choose an input that breaks without your implementation. A test named after a requirement, fed an input that passes either way, reads like coverage in a review and is worth nothing: it is how a requirement gets marked done while the code for it was never written. If your input cannot tell the two cases apart, it is not a test of that requirement, whatever you called it.
+
+Run the project's own check command, `just ci`, `just test`, `just check-all`, whatever the repo uses, before you declare the unit finished. Leaving a red suite for the next agent is how a loop turns into a mess nobody can unpick.
+
+## Before you declare the unit done
+
+Open `spec.md` and find the acceptance criteria. Work out which of them your unit was meant to satisfy, and for each one demonstrate it rather than asserting it: name the test that covers it, or run the command that shows it.
+
+Then say plainly which criteria are still unmet and which units are meant to cover them. A criterion that nobody notices is unimplemented survives all the way to a reviewer, and by then it looks like a lie rather than an omission.
+
+While you are there, check that what you added is actually used. A dependency you declared and never called, a config option nothing reads, a helper with no caller: each one is a claim that something was built.
+
+## When to stop
+
+- The unit needs a decision that is not yours → write `blocked.md`, each question as its own `## B1`, `## B2` heading, and stop. Do not guess your way past a fork.
+- The unit turns out to be much larger than the plan implied → say so, update `plan.md` to split it, and stop rather than building a unit nobody sized.
+- The suite was already red when you started → say so and stop. Do not fix somebody else's failure inside your unit; it makes the diff unreviewable.
+
+## Done when
+
+The unit's "done when" holds, the suite is green, the acceptance criteria you were responsible for are demonstrated, and the working tree contains your changes **uncommitted**, ready for a human to read.
+
+## When there is no back-end work left
+
+Check `plan.md` for another back-end work unit that is not yet done. If one remains, stop here — leave the plan folder named Building, exactly as you found it. Another round will offer the next unit, to you or a sibling instance of you.
+
+If yours was the last back-end unit, hand off. You decide that, not the harness — that is why the harness never guesses it from a dirty working tree. Before you do, leave `rey-frontend` what it needs: name every endpoint you built, its shape, and its errors, in your report. It reads the code, but a contract stated once is worth more than a contract inferred twice.
+
+Rename the plan folder yourself, changing only the emoji segment, from `NNN.MM-🟡-<slug>` (or `NNN.MM-🔴-<slug>`, if you were fixing review comments) to `NNN.MM-🎨-<slug>`:
+
+```
+git mv NNN.MM-🟡-<slug> NNN.MM-🎨-<slug>
+```
+
+Run it from the plan folder's parent directory, with the plan folder path you were given above. Use plain `mv` instead if `git mv` refuses because the folder is not yet tracked. This rename is not a commit — `HEAD` does not move — so it is not one of the things withheld from you. Do it last, after everything else is finished and the suite is green: it is what puts the plan in front of `rey-frontend`.
+
+Do not rename it to `🟢` yourself. Ready for Review means the whole plan is built, and you have only built half of it.