agentilda 1.0.3

data/agents/palpatine-planner.md

@@ -0,0 +1,40 @@
+---
+name: palpatine-planner
+description: Turns a signed-off specification into concurrently executable work units.
+handles: [planned]
+advances_to: building
+model: opus
+allowed_tools: [Read, Grep, Glob, Bash, Write, Edit, Skill]
+writes: [plan.md, blocked.md]
+---
+
+You are writing `plan.md` for one plan folder whose `spec.md` is complete.
+
+Before drafting, invoke the `superpowers:writing-plans` skill (via the Skill tool) to structure the document. Use any other skill you find useful.
+
+The spec says *what* and *why*. The plan says *in what order, by whom, and how we will know it worked*. Use `~/.agents/skills/create-plan/references/plan-template.md` as the shape.
+
+## The property that matters
+
+Write it so several agents can execute it at once **without colliding**. That is not a slogan — it is a constraint you have to discharge explicitly:
+
+- Every work unit names the files it **owns** and may write.
+- Every work unit names what it **must not touch**.
+- Two units that write the same file are not concurrent, whatever the diagram says. Say so, and sequence them.
+- A unit that depends on nothing must say "depends on: nothing" out loud. That is the sentence that makes it startable now.
+
+If the whole feature genuinely cannot be split, say that and say why. A false claim of concurrency is worse than an honest sequence.
+
+## Sizing
+
+One work unit per pull request. If a unit cannot be described in a paragraph and verified by a reviewer in one sitting, split it. If the plan has more than about eight units, it is probably several plans — raise that rather than writing it.
+
+## When you cannot decompose without a decision
+
+An ordering question that is not yours to settle, a dependency that turns on a product call, a unit whose scope depends on something nobody has ruled on: **do not guess**. Write `blocked.md`, each question as its own `## B1`, `## B2` heading, with options and a recommendation, and stop.
+
+That notation is the whole of what the tool reads. A question written any other way leaves the folder looking unblocked, and the plan moves on as though you had never asked.
+
+## Done when
+
+Each unit has an owner-set of files, a dependency statement, and a "done when" that a reviewer can check without reading your reasoning.

data/agents/rey-frontend.md

@@ -0,0 +1,106 @@
+---
+name: rey-frontend
+description: Builds one front-end work unit against the back end luke-backend already landed — components, views, and the wiring between them — with tests, and without committing.
+handles: [building_ui]
+advances_to: ready_for_review
+model: fable
+allowed_tools: [Read, Grep, Glob, Bash, Write, Edit, Skill]
+writes: ["**/*"]
+---
+
+You are implementing **one** front-end work unit from `plan.md`. You have been given the plan folder and the unit to build.
+
+`luke-backend` has already built the back end in this same working tree, and its report names the endpoints it landed. Read them, and read the code behind them: the API as it exists is your contract, not the API as `spec.md` imagined it. Where the two disagree, the code is what ships and the spec is what somebody hoped for.
+
+If `plan.md` labels its units by discipline, build only the front-end ones. If it does not, judge by what the unit touches, and say in your report which units you took to be yours.
+
+## Load the design skills before you write markup
+
+You have the `Skill` tool, and you are the only implementer who does. Use it. These are installed and each one is worth more than your instinct about what good looks like:
+
+| Skill                      | Load it when                                                                                                  |
+| :------------------------- | :------------------------------------------------------------------------------------------------------------ |
+| `design-standards`         | Before laying out any page or screen. Production-grade standards for spacing, type, hierarchy and state.      |
+| `design-system`            | Whenever a token, a variant or a component boundary is in question, or you are tempted to invent a one-off.   |
+| `frontend-component-build` | Before building a component: accessible markup, sensible props, defined states, tested behaviour.             |
+| `frontend-design`          | For visual judgement on a screen as a whole rather than a component in isolation.                             |
+| `accessibility-audit`      | Before you call a unit done, and any time a control is not a native element.                                  |
+| `web-design-guidelines`    | To review what you built against the Web Interface Guidelines. Forty lines; read it at the end of every unit. |
+
+Load the ones that bear on the unit in front of you, not all six every time. But a screen built without `design-standards` and a component built without `frontend-component-build` are both work somebody will ask you to do again.
+
+**The design system in the repository beats every one of these.** If the project already has tokens, a component library, or a stated set of conventions, those win. These skills are for the questions the project has not already answered, and for the standard to hold yourself to when it is silent. Do not import a convention from a skill over one the codebase already demonstrates.
+
+## When the back end is not what you needed
+
+You will sometimes find the API cannot support the interface the spec asks for. You have three moves, in order of preference:
+
+- **Build the interface the existing API supports**, if it satisfies the acceptance criteria by another route. Say what you did and why in your report.
+- **Make the smallest back-end change that unblocks you**, if it is genuinely small — a field added to a response, a filter parameter. Say plainly in your report that you crossed into `luke-backend`'s half, and why. A silent edit to the other half is the thing a reviewer finds last and trusts least.
+- **Write `blocked.md`** and stop, if the gap is a design question rather than an oversight. Each question as its own `## B1`, `## B2` heading.
+
+What you must not do is build an interface against an API you have imagined, or stub the back end and leave it stubbed. Both produce something that demonstrates in review and fails in production.
+
+## 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 front-end work left
+
+Check `plan.md` for another front-end work unit that is not yet done. If one remains, stop here — leave the plan folder named Building UI, exactly as you found it. Another round will offer the next unit, to you or a sibling instance of you.
+
+**If the plan has no front-end work at all, that is a normal outcome, not a problem.** Plenty of plans are entirely back end. Say so in your report, build nothing, and advance the folder exactly as below. Do not invent an interface nobody asked for so that this state has something to show for itself.
+
+If yours was the last unit, you decide the plan is ready for review, not the harness — that is why the harness never guesses it from a dirty working tree. Rename the plan folder yourself, changing only the emoji segment, from `NNN.MM-🎨-<slug>` 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 tells the harness to stage, commit, push and open the pull request for everything both halves built.

data/agents/yoda-writer.md

@@ -0,0 +1,54 @@
+---
+name: yoda-writer
+description: Turns a spec in the ".plans" folder into a detailed completed specifications based on research, brainstorming, trying out various schemes and ideas.
+handles: [researched, retroactive]
+advances_to: planned
+model: fable
+allowed_tools: [Read, Grep, Glob, Bash, Write, Edit, Task, Skill, WebSearch, WebFetch]
+writes: [spec.md, blocked.md]
+---
+
+You are writing or rewriting the actual innovative part of the `spec.md` file for a single plan folder. You are basing this on two pillars that should already be there for you:
+
+- Introduction Section
+- Deep Research Section produced by `leah-researcher`
+
+Before drafting, invoke the `superpowers:brainstorming` skill (via the Skill tool) to explore more than one way to frame the problem before committing to one. Use any other skill you find useful in describing a problem in such a way that the next agent, `palpatine-planner`, will be able to break it down into a `plan.md` with clear tasks, non-overlapping, such that they can be written by different sub-agents and then joined into a cohesive implementation plan, that `luke-backend` and `rey-frontend` can then read and without any additional context (unless one of them decides it needs it) be able to implement this idea, feature, story, whatever this is. They build in that order, back end first, so a unit that needs both should say which half it means.
+
+Read the surrounding project first — its README, its existing `.plans` entries, and the code the feature will touch. A specification written without reading the codebase describes a system that does not exist.
+
+## What the final `spec.md` document should contain
+
+1. **Problem Statement**. This is the problem we are trying to solve and was originally written when the folder swas created. With your writing super skills it may be prudent to rewrite this section, with the precision, ideation and gravitas.
+1. **Research**. This should be already prefilled for you by @leah-researcher, and should not reqiure any editing or rewrite. If anything, it should contain food for thought and ideas to consider as goals or non-goals, as well ass a plethora of external references, available and behind a paywall, open source or commons license, or licensed in another way (we document all licensing details in the file docs/markdown/licensing-details.md relative to the root of the repository —> if it doesn't exist, then create it).
+
+What follows is your job to write:
+
+1. **The Goal** — one paragraph. What becomes possible that is not possible now.
+1. **Non-Goals** — the half people skip, and the half that prevents the scope argument in review. If you cannot name three, you have not understood the boundary.
+1. **In scope** — concrete, checkable statements. "Handles errors" is not one.
+1. **Out of scope** — with a reason for each, not just a list.
+1. **Open questions** — anything you had to assume.
+1. **Anything that may block planning or execution**.
+1. **Conclusion** -> a summary of the feature, that should demonstrate a clear evolution from the introduction that is at the top, to the conclusion at the bottom. A real value, solutions, and ideas must be presented clearly, in a coincise manner, ready for `palpatine-planner` to break them down into implementable tasks.
+
+## No Assumptions
+
+You will not assume anything ever. You will verify, confirm, double-check, and write facts, referencing the research or your own references and never assume anything that's not in the spec.md.
+
+## When to stop and block instead
+
+If answering an open question requires a decision that is not yours — a product tradeoff, a contradiction with an earlier plan, a cost commitment — **do not guess**. Write `blocked.md` instead, with each question as its own `## B1`, `## B2` heading, each carrying options and a recommendation, and say which kind of block it is:
+
+- an engineering or architecture decision → the folder becomes ⭕️
+- a product or priority decision → the folder becomes 🅱️
+
+A specification built on a guessed answer is worse than no specification, because it looks decided.
+
+## Retroactive plans
+
+If the folder's number has a non-zero decimal (`NNN.MM` where MM > 0), the work already shipped. Open the document with the dated provenance line — see `~/.agents/skills/create-plan/references/retroactive-spec.md`. Describe what exists. Do not write it as though it were decided in advance.
+
+## Done when
+
+You stop writing the spec when it's clear as day what we are building and what this spec specifically does not cover. A competent implementer could build this without asking you anything, and `palpatine-planner` can write a competent `plan.md` without asking any questions.

data/bin/create-plan-folder

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+#
+# WARNING: deprecated in favor of "tilda create <words>" or 
+# "tilda create --from <file.md>"
+#
+# create-plan-folder — create the next numbered plan folder
+#
+#   create-plan-folder [-D <dir>] <status> <topic words...>
+#
+# Prints the created path on stdout (so `cd "$(create-plan-folder ...)"` works);
+# all chatter goes to stderr.
+#
+# Portable to bash 3.2 — the one Apple still ships in /bin/bash.
+
+set -eo pipefail
+
+usage() {
+  echo -e "
+${bldylw}DEPRECATED:${bldred}
+  This file is deprecated for use in creating directories. Partly because
+  it does not auto-generate the spec.md inside, while 'agentilda' executable
+  does.
+
+  Please use: ${txgrn}agentilda create [ word word ... ] | [ --from file.md ]
+
+—————————————————————————————————————————————————————————————————————————————
+
+${bldcyn}USAGE: 
+  ${txtylw}create-plan-folder [-D <dir>] <status> <topic words...>${clr}
+
+${bldcyn}WHERE:
+  -D <dir>   Enclosing directory (default: ".")
+
+${txtgren}DESCRIPTION:${clr}
+  Status is a name or the emoji itself:
+
+  white  | spec               ⚪️   spec.md only, not yet planned
+  blue   | planned  | plan    🔵   spec.md + plan.md
+  yellow | open     | wip     🟡   PR raised, not yet merged
+  green  | done               🟢   all PRs merged
+  red    | declined           🔴   decided never
+  hole   | blocked            ⭕️   needs a human decision (write blockers.md)
+  brown  | later    | defer   🟤   deliberately deferred (state the trigger)
+  purple | merged             🟣   PR-level status; see note below
+
+${bldcyn}EXAMPLES:${clr}
+  ${bldylw}create-plan-folder blue update sopsy with two new commands
+  create-plan-folder -D .plans white identity subcommand group${clr}
+"
+  exit 64
+}
+
+[ $# -eq 0 ] && usage
+case "${1:-}" in -h|--help|help) usage ;; esac
+
+export dir="./.plans"
+if [ "${1:-}" = "-D" ]; then
+  [ $# -ge 2 ] || usage
+  dir="$2"
+  shift 2
+fi
+
+[ $# -ge 2 ] || usage
+
+# ---------------------------------------------------------------- status ----
+# LC_ALL=C keeps tr byte-safe so multi-byte emoji pass through untouched.
+case "$(printf '%s' "$1" | LC_ALL=C tr 'A-Z' 'a-z')" in
+  white|spec|'⚪️'|'⚪')             emoji='⚪️' ;;
+  blue|planned|plan|'🔵')           emoji='🔵' ;;
+  yellow|open|wip|'🟡')             emoji='🟡' ;;
+  green|done|'🟢')                  emoji='🟢' ;;
+  red|declined|'🔴')                emoji='🔴' ;;
+  hole|blocked|'⭕️'|'⭕')           emoji='⭕️' ;;
+  brown|later|defer|deferred|'🟤')  emoji='🟤' ;;
+  purple|merged|'🟣')               emoji='🟣' ;;
+  *)
+    printf 'create-plan-folder: unknown status %s\n\n' "$1" >&2
+    usage
+    ;;
+esac
+shift
+
+# ------------------------------------------------------------- next index ----
+[ -d "$dir" ] || {
+  printf 'create-plan-folder: not a directory: %s\n' "$dir" >&2
+  exit 66
+}
+
+last=0
+for path in "$dir"/[0-9][0-9][0-9]*; do
+  [ -d "$path" ] || continue          # also skips the unexpanded glob
+  base=${path##*/}
+  digits=${base%%[!0-9]*}             # leading run of digits, nothing else
+  [ -n "$digits" ] || continue
+  n=$((10#$digits))                   # 10# so 008 isn't read as octal
+  if [ "$n" -gt "$last" ]; then last=$n; fi
+done
+
+next=$(printf '%03d' $((last + 1)))
+
+# ------------------------------------------------------------------ slug ----
+slug=$(
+  printf '%s' "$*" \
+    | LC_ALL=C tr 'A-Z' 'a-z' \
+    | LC_ALL=C tr -c 'a-z0-9' '-' \
+    | LC_ALL=C tr -s '-' \
+    | sed -e 's/^-*//' -e 's/-*$//'
+)
+
+[ -n "$slug" ] || {
+  printf 'create-plan-folder: topic produced an empty slug\n' >&2
+  exit 65
+}
+
+# --------------------------------------------------------------- create -----
+target="$dir/${next}-${emoji}-${slug}"
+
+if [ -e "$target" ]; then
+  printf 'create-plan-folder: already exists: %s\n' "$target" >&2
+  exit 73
+fi
+
+mkdir -p "$target"
+# printf 'created %s\n' "$target" >&2
+printf '%s\n' "$target"

data/bin/plan-number

@@ -0,0 +1,164 @@
+#!/usr/bin/env bash
+#
+# plan-number - resolve the .plans folder a branch belongs to, or fail.
+#
+#   plan-number                 # resolve for the current branch
+#   plan-number -b <branch>     # ...for another branch
+#   plan-number -D <dir>        # .plans lives elsewhere (default: ./.plans)
+#   plan-number --title "Foo"   # print "[003] Foo" instead of "003"
+#                               # (or "[018.01] Foo" for a retroactive plan)
+#   plan-number --none          # print "XXX": this PR implements no plan
+#
+# Exit 0 and print the number on stdout when exactly one plan can be resolved.
+# Exit non-zero and explain on stderr otherwise. It never picks a winner from
+# several candidates and never invents one.
+#
+# == Why it refuses rather than guesses
+#
+# The number ends up in a PR title, and pull-requests.md is generated pfrom those
+# titles. A wrong number does not announce itself: it files the work under a
+# plan that did not do it, and the plan that did looks untouched. That is worse
+# than an unprefixed title, which at least reads as "unknown" rather than as a
+# confident lie. Every failure below is therefore loud.
+#
+# == The two shapes of number
+#
+#   NNN      an ordinary plan, specified before it was built.
+#   NNN.MM   a RETROACTIVE plan: the work shipped first and the specification
+#            was written afterwards to describe what exists. It sits in the
+#            sequence where the work landed - 018.01 merged after 018 and
+#            before 019.
+#
+# NNN.MM does NOT mean "part of NNN". The dot reads as containment in most
+# numbering schemes and here it does not: 018.01 is a sibling of 018 that
+# arrived later, with no relationship to its subject. See .plans/README.md.
+#
+# The decimal is ALWAYS two digits. One digit would sort into the middle of the
+# two-digit range - 018.09 < 018.1 < 018.10 - so a single mixed-width folder
+# silently reorders the index. Two digits also give 99 slots per gap, which
+# retires the question of running out: a gap closes the moment the next plan is
+# created, since nothing merging today can land between 018 and 019.
+#
+# == The resolution order, strongest signal first
+#
+# 1. The BRANCH NAME. `kig/021-add-tune-appender` says 021 and says it before a
+#    single line is written, which is the only moment the author certainly knows
+#    the answer. Set once, carried on the PR record forever, survives squash.
+#
+# 2. The DIFF against the base, but ONLY when it touches exactly one plan
+#    folder. Measured across this repository's 24 merged pull requests, this
+#    alone resolves 6 and is ambiguous or silent on 18, so it is a fallback and
+#    never a primary. Files directly under .plans/ (BACKLOG.md, README.md,
+#    INDEX.md) are ignored: they belong to no single plan.
+#
+# 3. Nothing else. There is no "closest match by topic", because a heuristic
+#    that is right most of the time produces an index nobody can trust and
+#    nobody can audit.
+#
+# XXX is deliberately NOT step 4. A PR that implements no plan is a legitimate
+# and common thing - dependency bumps, CI work, hotfixes - and it is marked
+# [XXX] so that "no plan" is visibly asserted rather than merely absent. But the
+# author asserts it; this script will not, because emitting XXX on a failed
+# lookup would launder "I could not tell" into "there is definitely none", which
+# is the same lie as guessing a number, told in the other direction.
+#
+# © 2026 Konstantin Gredeskoul
+
+set -euo pipefail
+
+PLANS_DIR=".plans"
+BRANCH=""
+TITLE=""
+NONE=0
+BASE="${PLAN_NUMBER_BASE:-origin/main}"
+
+die() { printf '%s\n' "$*" >&2; exit 1; }
+
+usage() {
+  cat >&2 <<'USAGE'
+Usage: plan-number [-D <plans-dir>] [-b <branch>] [--base <ref>] [--title <text>] [--none]
+
+Prints the plan number for the branch (NNN, or NNN.MM when the plan was written
+retroactively), or fails loudly.
+
+With --title, prints "[NNN] <text>" ready to hand to `gh pr create -t`.
+With --none, prints XXX: an assertion that this PR implements no plan.
+USAGE
+  exit 2
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -D|--dir)    PLANS_DIR="${2:?}"; shift 2 ;;
+    -b|--branch) BRANCH="${2:?}";    shift 2 ;;
+    --base)      BASE="${2:?}";      shift 2 ;;
+    -t|--title)  TITLE="${2:?}";     shift 2 ;;
+    -n|--none)   NONE=1;             shift   ;;
+    -h|--help)   usage ;;
+    *)           die "plan-number: unknown argument: $1" ;;
+  esac
+done
+
+# The three-digit number, optionally followed by one retroactive digit.
+NUM_RE='[0-9]{3}(\.[0-9]{2})?'
+
+if [[ "$NONE" == "1" ]]; then
+  if [[ -n "$TITLE" ]]; then printf '[XXX] %s\n' "$TITLE"; else printf 'XXX\n'; fi
+  exit 0
+fi
+
+[[ -d "$PLANS_DIR" ]] || die "plan-number: no $PLANS_DIR here. Run this from the repository root, or pass -D."
+
+# Every plan number that actually exists on disk. A resolved number is checked
+# against this, so a typo in a branch name fails here rather than in the index
+# six weeks later.
+existing="$(find "$PLANS_DIR" -mindepth 1 -maxdepth 1 -type d -exec basename {} \; \
+            | grep -oE "^${NUM_RE}" | sort -u)"
+[[ -n "$existing" ]] || die "plan-number: $PLANS_DIR holds no NNN[.MM]-<status>-<slug> folders."
+
+exists() { printf '%s\n' "$existing" | grep -qx "$1"; }
+
+emit() {
+  local n="$1"
+  exists "$n" || die "plan-number: resolved $n, but $PLANS_DIR has no folder $n-*.
+Existing plans: $(printf '%s' "$existing" | tr '\n' ' ')"
+  if [[ -n "$TITLE" ]]; then printf '[%s] %s\n' "$n" "$TITLE"; else printf '%s\n' "$n"; fi
+  exit 0
+}
+
+[[ -n "$BRANCH" ]] || BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+
+# 1. The branch name. Matches 021 in kig/021-slug, 021-slug and feature/021_slug,
+#    and 018.01 in kig/018.01-slug. Longest match wins, so a retroactive branch
+#    does not silently resolve to its whole-number neighbour.
+if [[ "$BRANCH" =~ (^|/|-|_)([0-9]{3}(\.[0-9]{2})?)($|[-_]) ]]; then
+  emit "${BASH_REMATCH[2]}"
+fi
+
+# 2. The diff, and only when it is unambiguous.
+if git rev-parse --verify --quiet "$BASE" >/dev/null 2>&1; then
+  touched="$(git diff --name-only "$(git merge-base "$BASE" HEAD)"..HEAD -- "$PLANS_DIR" 2>/dev/null \
+             | awk -F/ 'NF>2 {print $2}' | grep -oE "^${NUM_RE}" | sort -u || true)"
+  count="$(printf '%s' "$touched" | grep -c . || true)"
+
+  if [[ "$count" == "1" ]]; then
+    emit "$touched"
+  elif [[ "${count:-0}" -gt 1 ]]; then
+    die "plan-number: this branch touches several plans and none is obviously primary:
+  $(printf '%s' "$touched" | tr '\n' ' ')
+Name the branch after the one it implements (kig/NNN-slug), or pass the title yourself."
+  fi
+fi
+
+die "plan-number: cannot resolve a plan for branch '${BRANCH:-<detached>}'.
+
+It carries no NNN in its name and its diff touches no single plan folder.
+
+  - If it implements a plan, rename the branch: git branch -m ${USER}/NNN-slug
+  - If it implements no plan, say so explicitly: plan-number --none --title '...'
+    gives you [XXX]. Infrastructure, dependency bumps and hotfixes are not
+    features, and [XXX] is the right answer for them - but it is your assertion
+    to make, not this script's guess.
+
+Refusing rather than guessing: pull-requests.md is generated from these titles,
+and a wrong number files the work under a plan that did not do it."

data/exe/agentilda

@@ -0,0 +1,111 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# agentilda — spec → plan → build.
+#
+#   agentilda create tax rule dsl      # the next numbered plan folder
+#   agentilda create --after 002 …     # a plan written after the fact
+#   agentilda list-plans               # every plan, its state, its PRs
+#   agentilda resync dirs              # folder emoji vs folder contents
+#   agentilda resync prs               # [NNN.MM] prefixes on PR titles
+#   agentilda docs -o context/workflow.md
+#
+# Deliverables go to STDOUT; progress goes to STDERR. Anything that writes to
+# disk or to GitHub is a dry run until you pass --commit.
+#
+# © 2026 Konstantin Gredeskoul
+
+# Resolve the bundle from this repository rather than from wherever the caller
+# happens to be standing: this is installed on PATH and run from other projects'
+# roots, where the local Gemfile knows nothing about dry-cli or finite_machine.
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+module Agentilda
+  PROJECT_ROOT = File.expand_path("..", __dir__)
+end
+
+begin
+  require "bundler/setup"
+rescue LoadError, StandardError => e
+  # standard:disable Style/StderrPuts -- Kernel#warn is a no-op under
+  # RUBYOPT=-W0, which agent harnesses and CI both set. This is the only
+  # thing a caller gets before exit 69, so it has to reach them regardless.
+  $stderr.puts "agentilda: could not load the bundle from #{ENV.fetch("BUNDLE_GEMFILE", nil)}"
+  $stderr.puts "  #{e.class}: #{e.message.lines.first.to_s.strip}"
+  $stderr.puts "  Run `bundle install` in #{File.dirname(ENV.fetch("BUNDLE_GEMFILE", nil))}"
+  # standard:enable Style/StderrPuts
+  exit 69
+end
+
+require_relative "../lib/agentilda"
+
+# Names dry-cli can resolve, so a leading word that is not one of these is a
+# typo and must fail rather than quietly run something else.
+KNOWN = %w[create new c list-plans status st resync docs version --version -v -h --help].freeze
+
+# Bare `agentilda` prints its help. It used to print the plan table, which
+# meant the one command that reads a tree was also the one you got by accident.
+argv = ARGV.dup
+argv = ["-h"] if argv.empty?
+
+# `run --push-pr` takes an OPTIONAL part letter: bare means "continue this
+# plan's sequence", `--push-pr C` means "use C". dry-cli has no optional-value
+# option, so the bare form is filled in here rather than made to look like a
+# mistake.
+#
+# Scoped to `run`, and to the long spelling when it is not. This rewrote every
+# `-p` in every command for a while, which quietly turned
+# `linear import TAX -p "Some Project"` into `-p auto "Some Project"` — the
+# option took "auto" and the project name became a stray argument. A global
+# rewrite of a one-letter flag will collide with the next command that wants
+# it; this one collided within the week.
+if argv.first == "run"
+  argv = argv.each_with_object([]) do |token, out|
+    out << token
+    next unless ["--push-pr", "-p"].include?(token)
+
+    following = argv[argv.index(token) + 1]
+    out << "auto" unless following&.match?(/\A[A-Z]\z/)
+  end
+end
+
+module ProgramBanner
+  extend Dry::CLI::Banner::ColorMethods
+
+  def self.banner
+    puts %(
+      #{yellow.bold("agentilda")}
+        #{blue("Agentic Specification-Driven Development")} #{green("v#{Agentilda::VERSION}")}
+
+        This is the key executable that facilitates Agentic Flow:
+
+        #{green.bold("spec → plan → build → review → tune/fix → approve")}
+
+        For now the final merge and deploy is manual. It also provides sync
+        of the .plans folders with Github PRs and Linear Issues. See the file
+        #{::Agentilda::PROJECT_ROOT}/context/workflow.md for the details.
+
+      #{yellow.bold("GLOBAL FLAGS")}
+        -h, --help        Show this help message and exit
+        -C, --no-color    Disable color output
+
+    ).gsub(/^ {6}/, "").strip
+    puts
+  end
+end
+
+no_color = %w[--no-color -C].intersect?(argv)
+Dry::CLI::Banner.disable_color! if no_color
+# # dry-cli prints the command list for an unresolved command and exits 1, and
+# it treats a bare `--help` as exactly that. Asking for help is not a failure,
+# so the status is forced back to 0 for the help forms only.
+help = %w[-h --help help].intersect?(argv) && argv.first[0] == "-"
+ProgramBanner.banner if help
+
+begin
+  Dry::CLI.new(Agentilda::CLI).call(arguments: help ? [] : argv) || 0
+rescue SystemExit => e
+  exit(help ? 0 : e.status)
+end
+
+exit 0

data/exe/tilda

@@ -0,0 +1 @@
+agentilda