allye-pi 1.5.1

package/packages/allye-pi/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}

package/skills/agent-runtime/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: agent-runtime
+description: Contract for driving an external agent runtime — spawning real agent processes in panes, dispatching work to them, and collecting results. Use when the session hook reported a runtime and work is about to be dispatched in parallel.
+version: "1.0"
+category: methodology
+---
+
+# Agent Runtime
+
+An **agent runtime** owns real agent processes the human can watch, attach to, and take
+over. This skill defines what the plugin needs from one, so the Orchestrator can drive
+any runtime that satisfies the contract rather than one specific tool.
+
+Load this only when the session hook reported a runtime. Without one, dispatch falls back
+to the manual handover and the dispatched-subagent modes, both of which work unchanged.
+
+Concrete commands for the runtimes we implement live in `references/`. This file is the
+contract; the reference is the implementation.
+
+<!-- adapted from ogulcancelik/herdr SKILL.md (Apache-2.0) — the primitive vocabulary and the safety rules -->
+
+## The five primitives
+
+### 1. detect
+
+Answer two questions, not one: does the tool exist, and **is this session running inside
+it**. A binary on `PATH` says nothing about the second.
+
+A runtime that fails any part of detection is **absent**, never **broken**. A version
+mismatch, an unreachable server, a missing environment variable — each means fall back to
+asking the user manual-or-automatic. A degraded runtime must never block delivery.
+
+### 2. spawn
+
+Produce an isolated execution location and return a **stable identifier** for it. The
+location must be a shell at an interactive prompt with nothing running in the foreground,
+and creating it must not steal the human's focus.
+
+<HARD-GATE>
+**Wait for the shell; do not merely inspect it.** A pane created a moment ago is often
+still running the shell's startup — a banner, a version manager, a greeting. Dispatching
+into it fails. Poll for a bare shell with a bound, and treat a pane still busy after the
+bound as a problem to report rather than one to keep waiting on.
+</HARD-GATE>
+
+### 3. dispatch
+
+Deliver the briefing and **confirm it was accepted**.
+
+<HARD-GATE>
+Confirmation is part of the primitive, not an optional check. Sending text to an agent
+that is idle can leave it sitting in the input box unsubmitted — the agent looks dispatched
+and is not. After dispatching, read the agent's state back. If it has not moved to a
+working state, submit explicitly and read it again.
+</HARD-GATE>
+
+### 4. wait
+
+Block until the agent's lifecycle state settles. **Always with a timeout** — an unbounded
+wait on a stalled agent hangs the whole delivery.
+
+<HARD-GATE>
+A settled state does not prove completion. "Idle" can mean finished, or an API error
+mid-turn, or a question sitting unanswered on screen. An "unknown" state proves nothing at
+all.
+
+Runtime state is **evidence**. The verdict comes from `collect`.
+</HARD-GATE>
+
+**`wait` is not how the Orchestrator blocks — it is how the runtime's lifecycle becomes an
+event in whatever system the Orchestrator actually lives in.** Run it as a background job
+of the host harness so its completion arrives as a notification. Polling the agent's state
+by hand works and is wrong: it makes every check an arbitrary interruption, and a finished
+agent sits unnoticed until the next one. **A dispatch without a wait registered is a story
+nobody is listening for**, so registering it is the closing step of `dispatch`, not a
+separate thing to remember.
+
+A future runtime satisfies this primitive only if its wait can be bridged that way.
+
+### 5. collect
+
+Read the result **from Allye**:
+
+- `work_children(id: "{story uuid}")` — the real status of every task
+- `memory_search("Review {STORY-KEY}")` — the review findings
+- `memory_search("Implementation {TASK-KEY}")` — what was done and why
+
+The terminal is for human observation and for diagnosing a stuck agent. It is never the
+source of the result, for three reasons that hold regardless of what the terminal can show:
+
+- A record in Allye is structured and machine-readable; a transcript is prose to be parsed.
+- The Orchestrator can read it from a pane it never created, and after that pane is closed.
+- It works identically for every runtime, including those with no output-read primitive at
+  all — which is most of the category.
+
+There is also a documented failure mode where full-screen agents render on the terminal's
+alternate screen and those rows never reach scrollback, making a long report unrecoverable.
+**Treat that as a caveat, not the reason.** It did not reproduce in testing on 2026-07-26,
+and a design justified by a failure that does not reproduce is one experiment away from
+being abandoned for the wrong reason.
+
+An agent that has settled but left no trace in Allye has produced an **incomplete report**.
+Treat it the way §5 of `orchestrator` already treats one: ask for more, do not wave it
+through.
+
+## The obligation on the dispatched side
+
+The contract closes only because the dispatched agent carries the other half:
+
+> **Before settling, leave a durable trace in Allye.** Executor: task statuses advanced,
+> plus an implementation memory. Reviewer: a memory holding the findings.
+
+This is already what `execution` and `review` do. Here it becomes load-bearing rather than
+good practice — it is the entire result channel.
+
+## Teardown
+
+Destroy only what you created, and only after the work it held is merged and verified.
+Never close a pane, tab, workspace, or session the plugin did not create. Never stop the
+runtime's server.
+
+## Implementations
+
+- Herdr — `references/herdr.md`

package/skills/agent-runtime/references/herdr.md

@@ -0,0 +1,154 @@
+# Runtime implementation: Herdr
+
+Herdr is a terminal multiplexer that recognizes coding agents inside panes and exposes
+them over a CLI. Its mental model: `workspace (w1) → tab (w1:t1) → pane (w1:p1)`, with an
+**agent** being a recognized process inside a pane. A pane exists whether or not it holds
+an agent, and starting an agent never creates or moves layout — topology is the caller's job.
+
+Agent names must match `[a-z][a-z0-9_-]{0,31}` and be unique among live agents. Use
+`story-beac-1716`, never `BEAC-1716`.
+
+## detect
+
+```bash
+[ "${HERDR_ENV:-}" = "1" ] || exit 1        # not inside a pane
+command -v herdr >/dev/null || exit 1
+herdr status | grep -q 'compatible: yes' || exit 1
+```
+
+The session hook already runs this and reports the result. Re-run it only if a dispatch
+fails in a way that suggests the server went away.
+
+Caller context is injected into every managed pane: `$HERDR_PANE_ID`, `$HERDR_TAB_ID`,
+`$HERDR_WORKSPACE_ID`.
+
+## spawn
+
+```bash
+herdr pane layout --pane "$HERDR_PANE_ID"
+```
+
+Read the pane's dimensions from `.result.layout.area`. **Split a wide pane to the right and
+a narrow or tall one down.** Repeated splits in one direction produce columns too narrow to
+read.
+
+```bash
+herdr pane split --current --direction right --cwd "$CWD" --no-focus
+# new pane id: .result.pane.pane_id
+```
+
+`--no-focus` keeps the human where they were. **Wait** for the pane to reach a bare shell —
+a pane created a second ago is usually still running the shell's startup, and `agent start`
+fails with `agent_pane_busy`:
+
+```bash
+for _ in $(seq 1 10); do
+  FG=$(herdr pane process-info --pane "$PANE" | jq -r '.result.process_info.foreground_processes[0].name')
+  case "$FG" in zsh|bash|sh|fish) break;; esac
+  sleep 3
+done
+```
+
+Bounded, not infinite. A pane still busy after thirty seconds is a problem to report.
+
+## dispatch
+
+```bash
+herdr agent start {name} --kind {kind} --pane {pane_id} --timeout 120000 -- {native args}
+herdr agent prompt {name} "$(cat {briefing file})"
+herdr agent get {name} | jq -r '.result.agent.agent_status'
+```
+
+The third command is mandatory, not diagnostic — and **expect to need the fourth.**
+Prompting an idle agent left the text unsubmitted in every observed dispatch, so treat this
+as a two-step operation rather than a rare branch. When the status does not read `working`:
+
+```bash
+herdr agent send-keys {name} enter
+herdr agent get {name} | jq -r '.result.agent.agent_status'
+```
+
+`--kind` accepts, among others: `claude`, `codex`, `opencode`, `pi`, `gemini`, `cursor`,
+`copilot`, `amp`, `droid`. Native arguments pass verbatim after `--`.
+
+Named failure: `agent_prompt_stalled`, returned when no lifecycle change is observed within
+five seconds of prompting a non-working agent.
+
+## wait
+
+```bash
+herdr agent wait {name} --timeout 3600000
+```
+
+**Run it as a background job of your own harness**, so its exit arrives as a notification
+rather than something you have to remember to check. That bridge is the point of the
+primitive — see the contract's §4. Do not poll `agent get` in a loop: the wait is
+server-side and event-driven, and polling turns every check into an arbitrary interruption
+while leaving a finished agent unnoticed between them.
+
+Across all panes at once:
+
+```bash
+herdr agent list | jq -r '.result.agents[] | "\(.pane_id)\t\(.agent)\t\(.agent_status)\t\(.cwd)"'
+```
+
+`herdr agent read` returns **plain text, not JSON** — piping it to `jq` fails.
+
+To understand why a pane was classified as it was:
+
+```bash
+herdr agent explain {name} --json --verbose
+```
+
+## collect
+
+Read from Allye — see the contract. The terminal is diagnostic only:
+
+```bash
+herdr agent read {name} --source recent-unwrapped --lines 200
+```
+
+Sources are `visible`, `recent`, `recent-unwrapped`, and `detection`. Prefer
+`recent-unwrapped` for transcripts. If raising `--lines` reveals nothing more, the agent is
+rendering on the alternate screen and the rows are gone — this is expected, and is why the
+result channel is Allye.
+
+## answering a blocked agent
+
+A `blocked` state means Herdr recognized an approval or question UI. Read the pane before
+answering — the question may be one whose options are all wrong:
+
+```bash
+herdr agent read {name} --source recent-unwrapped --lines 120
+```
+
+If a selection UI is open and your answer is not one of its options, **dismiss it first**.
+Sending a prompt into an open menu risks the text being read as menu navigation:
+
+```bash
+herdr agent send-keys {name} esc
+```
+
+Then dispatch normally, including the submit confirmation — a freshly dismissed menu leaves
+the agent idle, which is exactly the state where a prompt lands unsubmitted.
+
+## teardown
+
+```bash
+herdr pane close {pane_id}
+```
+
+Only panes the plugin created, and only after §7.1's merge gates have passed.
+
+## Safety rules — never widened
+
+- Never run bare `herdr` for discovery; it launches or attaches the TUI. Discover with
+  `herdr agent`, `herdr pane`, `herdr workspace` — a group name with no subcommand prints
+  its help.
+- Never probe a mutating command by omitting its arguments. `herdr workspace create` is
+  valid with defaults and will execute.
+- Never run `herdr server stop`. Never kill the main Herdr process.
+- Never close a workspace, tab, pane, or session the plugin did not create.
+- Always pass `--timeout`. Omitting it allows an indefinite wait.
+- Parse identifiers out of JSON responses. Never derive them from sidebar order or from
+  the examples above.

package/skills/board-progression/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: board-progression
+description: Rules for moving work items between statuses in Allye boards. Covers work_status_next, work_status_done, and status categories.
+version: "1.2"
+category: methodology
+---
+
+# Board Progression
+
+How to move work items between statuses on Allye boards, correctly.
+
+---
+
+## 1. Status Categories vs. Status Names
+
+The MCP client can only **confirm** 4 status categories — `work_statuses()` (`work_items.py`) groups every status under a hardcoded `category_order`:
+
+| Category (confirmed) | Meaning |
+|----------|---------|
+| `proposed` | Not yet started (backlog/todo-like) |
+| `in_progress` | Actively being worked on |
+| `done` | Completed and verified |
+| `cancelled` | Will not be done |
+
+That's the only taxonomy the MCP client source guarantees. Specific status **names** are team-configurable `WorkflowStatus` records mapped onto those 4 categories via board columns — not enumerable or guaranteed from the client code alone, and a given team's board may use different names or skip some of them.
+
+### The team's pipeline is data. Read it.
+
+Allye is multi-tenant. Four presets ship — Solo, Startup, Standard, Enterprise — and every
+team customises from there, so **there is no status list to memorise and no ordering to
+assume.** A skill that names a status has guessed about somebody else's board.
+
+Only three things are stable enough to build a rule on:
+
+| Stable | Why |
+|---|---|
+| The four categories: `proposed`, `in_progress`, `done`, `cancelled` | A schema enum. Every status maps to exactly one. |
+| The three pipelines: `product`, `engineering`, `shared` | A schema enum. `product` carries epics and features; `engineering` carries stories and below; `shared` holds the terminal states. |
+| The board's own ordering | Whatever it is, it is what `work_status_next` walks. |
+
+Discover the rest:
+
+```
+work_statuses()    → every status the team has, grouped by category, in position order
+board_columns()    → the columns of a specific board
+```
+
+**Two things `work_statuses()` does not tell you today**, and planning around them is the
+difference between a working transition and a surprised one:
+
+- **`position`, `pipeline`, and `description` are not returned.** They exist on the record —
+  the seed writes all three — but the MCP formatter emits only name, key, id, and colour.
+- **`board_columns()` returns names and ids only** — no status-to-column mapping and no
+  ordering. The visible subset a given board shows cannot be reconstructed from it.
+
+Together these mean **you cannot reliably predict the next status.** So do not:
+
+<HARD-GATE>
+Move one status at a time, then **read back** the status you actually landed on. Never
+assume a transition took you where you expected, and never chain several moves on a
+prediction. One extra read per transition costs nothing next to a cascade that silently
+skipped four gates.
+</HARD-GATE>
+
+For reference only, these are the eighteen statuses the presets seed — **an example of one
+tenant's configuration, not a list to code against**: `idea`, `researching`, `designing`,
+`specifying`, `backlog`, `todo`, `in_progress`, `code_review`, `security_scan`, `qa_testing`,
+`doc_review`, `deploy_staging`, `qa_staging`, `deploy_preprod`, `qa_preprod`, `deploy_prod`,
+`done`, `cancelled`.
+
+---
+
+## 2. How `work_status_next` Works
+
+`work_status_next` moves a work item to the **next logical status** in the board progression.
+
+### Resolution logic
+
+1. Collects all visible statuses from non-archived boards
+2. Orders them by: `board.position → column.position → BoardColumnStatus.position`
+3. Deduplicates: first occurrence wins
+4. Finds the current status in this ordered list
+5. Moves to the next status in the list
+
+### Edge cases
+
+| Situation | Behavior |
+|-----------|----------|
+| Current status is NOT in any visible board | Moves to the **first** status in the list |
+| Current status is the **last** in the list | Returns an **error** — cannot move forward |
+| Item has no status set | Moves to the **first** status in the list |
+
+### When to use
+
+```
+work_status_next(id: "{work item uuid}")
+```
+
+Use it for **forward progression**, one status at a time, as each step's work actually finishes — how progression differs by pipeline and item type is in §5.
+
+### When NOT to use
+
+- Don't use to skip statuses (e.g., backlog → done)
+- Don't use to go backward — there is no `work_status_prev`
+- Don't call repeatedly to "fast forward" through multiple statuses without doing the actual work
+
+---
+
+## 3. How `work_status_done` Works
+
+`work_status_done` moves a work item directly to the "done" status, regardless of its current position.
+
+### Resolution logic
+
+1. Looks for a status mapped to a column with `is_done_column = true`
+2. Fallback: picks the first status with `category === "done"`
+3. Sets `completed_at = now()` on the work item
+
+### When to use
+
+```
+work_status_done(id: "{work item uuid}")
+```
+
+Use this when work is **fully complete and verified**:
+- All acceptance criteria are met
+- Tests pass
+- Review is approved (if applicable)
+
+<HARD-GATE>
+Do NOT call work_status_done unless the work is genuinely complete.
+"Almost done" is not done. "Tests are mostly passing" is not done.
+Verify all acceptance criteria before marking an item as done.
+</HARD-GATE>
+
+---
+
+## 3.1 Where an agent's authority ends
+
+> **An agent drives everything that is verification. It stops at the first gate that changes
+> the world outside the repository.**
+
+Deploying does that. Verifying does not. The rule survives renaming because it describes what
+a gate *is*, not what it is called — which is the only kind of rule that works when every
+team configures its own statuses.
+
+In practice, on the seeded presets: reviewing, scanning, testing, and updating docs are all
+verification and all satisfiable by an agent. Every deploy stage, and any validation
+performed in a deployed environment, is not.
+
+<HARD-GATE>
+`work_status_done` is **not** the exit from a pipeline an agent cannot finish. Calling it
+from four statuses away records "done" for work that never passed the gates in between.
+
+Use it only when the item's next status **is** the done status. Otherwise stop at the last
+gate you satisfied and say plainly which gate is next and who owns it.
+</HARD-GATE>
+
+An unrecognised status is treated as a stop, not a pass. Ask once who satisfies it, record
+the answer in the team's delivery configuration, and never ask again.
+
+---
+
+## 4. Checking Available Statuses
+
+Before moving items, understand what statuses exist:
+
+### List all statuses
+
+```
+work_statuses()
+```
+
+Returns all available statuses with their categories and names.
+
+### View board columns
+
+```
+board_columns()
+```
+
+Returns the board's columns for the given `board_id` — each rendered as `- {column name} (ID: {column id})`. Note: this tool's text output does not surface which statuses map to which column, nor an explicit ordering field (`boards.py`'s `board_columns` action only formats `name` and `id` per column) — that richer structure may exist in the underlying API but isn't exposed here. Use it to confirm which columns exist on a board; pair it with `work_statuses()` for status names/categories.
+
+---
+
+## 5. Progression Patterns by Item Type
+
+Progression differs by pipeline, not only by type. **Epics and features live on the `product`
+pipeline; stories, bugs, hotfixes, tasks, spikes, and subtasks live on `engineering`.** A
+cascade from task to epic therefore crosses pipelines, and the statuses available on each side
+are different sets.
+
+What holds regardless of the team's configuration:
+
+- **Parents move because children moved.** A story advances when its tasks do; a feature when
+  its stories do; an epic when its features do. Never the other way round.
+- **A parent never reaches the done category while any child is outside it.** This is the one
+  rule that failed in practice: a story closed with seven of fifteen tasks still mid-pipeline,
+  because closing it was the only exit the flow offered. Stopping is the exit.
+- **The Executor advances a task only to the first review gate.** The move past that is the
+  Orchestrator's, after review clears — see `orchestrator` §6.
+
+---
+
+## 6. Common Mistakes
+
+| Mistake | Why it's wrong | Do this instead |
+|---------|---------------|-----------------|
+| Moving story to done before all tasks are done | Misrepresents progress | Check `work_children` first — all tasks must be done |
+| Marking a task done as soon as its own tests pass | Done requires review approval, not just green tests | `work_status_next` once, to the first review gate, and stop; the Orchestrator carries it from there — see §3.1 |
+| Skipping statuses with repeated `work_status_next` | Loses tracking fidelity | Only advance when the work for that status is actually complete |
+| Moving to in_progress without planning | No tasks = no accountability | Run Technical Planning first, create tasks, then advance |
+| Forgetting to check board structure | Different teams may have different progressions | Always check `board_columns` if unsure about available statuses |
+| Moving a cancelled item to done | Contradictory | Cancelled items stay cancelled |

package/skills/branch-landing/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: branch-landing
+description: Decide and execute what happens to a branch once its work is done — merge, open a pull request, or leave it — then tear down the worktree and pane without losing anything. Use when a story's implementation is complete, or when another skill needs the teardown sequence.
+version: "1.0"
+category: methodology
+---
+
+# Branch Landing
+
+Code that is written and reviewed is not yet delivered. It sits on a branch, and something has to decide what happens to it. This skill is that decision and the sequence that carries it out.
+
+## 1. A branch does not land ahead of its story
+
+<HARD-GATE>
+Before anything else, check where the story actually is.
+
+If the story is parked at a pipeline gate — waiting on QA, a scan, a deploy, anything the team satisfies outside this session (see `board-progression` §3.1) — **the branch waits with it.** Do not merge, do not open a pull request, do not remove the worktree.
+
+Landing code whose story never passed its gates is the same defect as closing a story to tidy the board, one layer down. Say which gate the story waits at, and stop.
+</HARD-GATE>
+
+The work item is the authority on whether the work is done. The branch follows it; it never leads.
+
+## 2. Ask how the work should land
+
+Teams integrate differently and the plugin has no basis to guess. Ask once, with a recommendation so accepting takes a word:
+
+| Option | What happens | When it fits |
+|---|---|---|
+| **Pull request** | Push the branch, open a PR against the base, leave everything standing | Any team that reviews before merging, or where CI runs on the PR |
+| **Merge locally** | Merge into the base in the main checkout, then tear down | Solo work, or a change already reviewed by the two axes |
+| **Leave it** | Push for safety, change nothing else | The human wants to look first, or the work is paused |
+
+The base branch is per-repo and comes from the `Allye Delivery Configuration` Core Document — **never assumed.** Repos with a git-flow layout branch from `develop`; repos releasing from trunk branch from `main`.
+
+**Nothing merges into the base branch without the human choosing it in this conversation.** A merge is not reversible in the way an unmerged branch is, and no amount of green review substitutes for being asked.
+
+## 3. The sequence, when merging locally
+
+Every step is a gate. One story at a time; do not batch.
+
+```
+1. GATE:  git -C <worktree> status --porcelain   must be EMPTY
+          dirty → STOP, escalate. Do not merge, do not remove.
+2. git push -u origin <branch>
+3. In the MAIN checkout, on the base:  git merge --no-ff <branch>
+4. Conflicts in shared wiring files are expected when parallel work
+   touched the same composition root. Resolve by CONSOLIDATING into one
+   instance — never by picking a side.
+5. Rebuild, typecheck, run tests BEFORE committing the merge
+6. git worktree remove <path>          ← without --force
+7. Close the runtime pane              ← only after step 6
+```
+
+### The three locks
+
+Each exists because it prevents one specific way work disappears. They look skippable right up until they are not.
+
+| Lock | What it prevents |
+|---|---|
+| **Push before removal** (2) | The branch exists on the remote before anything is destroyed. After this, no local accident loses the work. |
+| **`worktree remove` without `--force`** (6) | Git refuses a dirty worktree. That refusal is the last safety net; bypassing it by reflex is how uncommitted work vanishes. |
+| **Pane closes last** (7) | While the pane lives, the session's reasoning is inspectable. Close it before a validated merge and the *why* is gone, even though the *what* survives in the diff. |
+
+### When merging is not the choice
+
+**Pull request:** push, open the PR against the base, and stop. Worktree and pane stay — review feedback arrives there. Record the PR reference on the story so the next session finds it.
+
+**Leave it:** push, and change nothing else. Say plainly what is standing: branch, worktree, pane.
+
+## 4. Never
+
+- **Never merge into the base branch unasked.** §2.
+- **Never force-push.** A force-push rewrites what step 2 exists to protect.
+- **Never delete a branch.** Merged branches are cheap and are the record of how something was built. Removing a worktree is not deleting its branch, and should not become it.
+- **Never destroy what you did not create.** A worktree or pane that predates this session belongs to someone else.
+
+## 5. Abandoned work
+
+A story that failed, was cancelled, or stalled gets **no cleanup at all**. Worktree, branch, and pane all stay.
+
+Visible litter costs far less than deleted work, and an abandoned branch is often the only record of an approach that was tried and rejected — which is worth more than the disk it occupies.
+
+## 6. Record where it landed
+
+Once the work has landed, the branch may be the only durable trace outside the diff. Carry the reference into the delivery memory (`memory_save`, `sector: "knowledge"`): the branch name, the merge commit or PR reference, and the base it landed on.
+
+A memory that says a story was delivered, without saying where the code went, is a memory that sends the next reader searching.