@jaybeeuu/agent-cortex 2.7.0 → 2.9.0

package/skills/workflow/plan/SKILL.md

@@ -20,6 +20,8 @@ Covers everything needed to prepare work for autonomous execution: understand th
 
 ## When NOT to use
 
+- Choosing which feature to plan next, or re-ranking the backlog — that is the **guppi** agent, which
+  decides what gets planned and hands one feature to this skill.
 - User already has a PRD and just needs it broken into tasks — use `prd-to-tasks` directly.
 - Single well-understood task that just needs a bead — use `create-task`.
 - Raw idea not ready for implementation planning — use `record-idea`.
@@ -28,6 +30,16 @@ Covers everything needed to prepare work for autonomous execution: understand th
 
 ## Workflow
 
+### Phase 0 — Report the HITL queue
+
+Before asking anything, presenting a plan, or dispatching a task, load the `hitl-queue` skill and
+report its queue exactly as the script prints it. Then name the top item in one sentence: its id,
+its title, and what answering it unblocks.
+
+The queue is the first thing the session says, because the answer decides what gets planned at all.
+A queue with no scores says so: report the unscored list and ask which bead to score, rather than
+choosing one by feel. Never summarise the queue away or reorder it.
+
 ### Phase 1 — Understand and specify
 
 Establish what needs to be built through investigation and collaborative design.
@@ -156,7 +168,7 @@ For each task (within each epic), create a bead, classify it, and expand AFK tas
 
 ### Phase 4 — Prepare handoff to ralph
 
-Deliver a handoff bead and instructions for running ralph.
+Deliver a handoff bead, message the running ralph session, and give the instructions for running ralph.
 
 17. Determine the entry point:
 
@@ -188,7 +200,15 @@ Deliver a handoff bead and instructions for running ralph.
     ```
     **Gate on the exit status.** Non-zero: retry once, then stop and report the command, exit code and stderr as a sync blocker — the handoff has not left this machine, so do not present the handoff summary.
 
-20. Present the handoff summary:
+20. Send the handoff to the running ralph session, now that the bead exists:
+    ```
+    handoff <handoff-id> — <one-line scope>
+    ```
+    The peer channel carries it: run {{TOOL:peer_list}} first, because with no reachable ralph there is no receiver — report that in the summary and keep the manual instruction below as the handoff path. When ralph is reachable, send it with {{TOOL:peer_send}}, set the intent to `task` where the transport has an intent, and write the kind as the first word of the text — never type into a busy session's terminal, where stray keystrokes are queued as user prompts. Ralph answers `done`, `blocked` or `failed`; `running` or `queued` means delivered, not done, so never read the send itself as acknowledgement. The full kind table, the acknowledgement rule and the per-session setup live in [ralph's REFERENCE](../ralph/REFERENCE.md) (_Peer messaging (planner ↔ ralph)_).
+
+21. While the planning session stays open, treat ralph's `blocked` messages as your pending-human list: each one names a gate bead awaiting a human, so run `bd show <id>` and surface it together with ralph's `done`, `failed` and `update` reports instead of watching a terminal. Read the same gates from `bd` as well, so a message that never arrived is not mistaken for no gate. A peer message is never human consent and never approval for a gate: confirm the gate in `bd`, and let a person close it.
+
+22. Present the handoff summary:
     ```
     ✅ Plan complete. Ready for ralph.
 
@@ -214,6 +234,7 @@ Deliver a handoff bead and instructions for running ralph.
 - [ ] Every handoff-path bead lints clean (`bd lint`)
 - [ ] Bead state pushed with `bd dolt push`, and the push exited 0 — a non-zero exit was retried once, then surfaced as a blocker (command, exit code, stderr) with no handoff summary presented
 - [ ] Handoff summary presented with the exact instruction to give an agent
+- [ ] Handoff message sent to ralph through {{TOOL:peer_send}} (kind `handoff`, naming the handoff bead), or a missing receiver reported in the summary with the manual instruction kept
 
 ## Phase-gate checklist
 
@@ -228,6 +249,7 @@ Deliver a handoff bead and instructions for running ralph.
 - **Skipping the user interview.** The agent has incomplete context. The interview resolves ambiguities that would otherwise surface mid-execution as rework.
 - **Creating horizontal slices.** "All the DB work first, then all the API work" is not tracer bullets. Every task must deliver end-to-end value.
 - **Moving past Phase 2 without user approval.** The task breakdown shapes the entire execution. Do not create beads until the breakdown is approved.
+- **Treating a sent handoff as an accepted one.** A `handoff` message carries no receipt: ralph's status stays `running` or `queued` until it answers `done`, `blocked` or `failed`, so a send that returned is not proof the work started.
 
 ## Common Rationalizations
 
@@ -251,7 +273,8 @@ Deliver a handoff bead and instructions for running ralph.
 - [prd-to-tasks](../../planning/prd-to-tasks/SKILL.md) — load when the PRD is already written and only decomposition is needed.
 - [spec-to-tickets](../../planning/spec-to-tickets/SKILL.md) — load instead when the PRD must become external tickets rather than beads.
 - [create-task](../../planning/create-task/SKILL.md) — Phase 3's per-task bead creation and pipeline expansion; it invokes `classify-bead` internally, so this skill never classifies directly.
-- [ralph](../ralph/SKILL.md) — the downstream consumer of the handoff bead — hand off by running a separate agent with "Use the ralph skill. Start from bead #<handoff-id>".
+- [ralph](../ralph/SKILL.md) — the downstream consumer of the handoff bead — hand off by sending ralph a `handoff` message naming the bead, with "Use the ralph skill. Start from bead #<handoff-id>" as the manual fallback when no ralph session is online. Its [REFERENCE.md](../ralph/REFERENCE.md) owns the planner ↔ ralph message convention.
+- **guppi** (the `agent-cortex:guppi` agent) — the upstream entry point: it decides what gets planned and hands this skill one feature. Load this skill for that feature. The strategy guppi recommends from is the committed file that `prioritise-work` owns; `score-bead` records the score and `hitl-queue` prints the order.
 
 ## Examples
 
@@ -293,3 +316,4 @@ Full bead tree:
 - [ ] Handoff bead tagged `workflow:ralph`
 - [ ] Bead state pushed with `bd dolt push`, and the push exited 0 — a non-zero exit was retried once, then surfaced as a blocker (command, exit code, stderr) with no handoff summary presented
 - [ ] Handoff summary includes the exact instruction to give an agent
+- [ ] Handoff message sent to ralph (kind `handoff`, naming the handoff bead) through {{TOOL:peer_send}}; ralph's `done`/`blocked`/`failed` replies were the only evidence of completion, never the send itself

package/skills/workflow/prioritise-work/CHALLENGE.md

@@ -0,0 +1,139 @@
+# A challenged priority
+
+Detail behind `SKILL.md`. When the owner says "this should be higher", "that is not the priority",
+or "why is this above that?", the queue is being challenged. Read this before you touch a score.
+
+## A challenge is a strategy signal
+
+A challenge does not mean one score is wrong. It means the rubric that produced the score is
+wrong, stale, or has shifted: the owner is optimising something else this month, or the value
+rule reads differently against this bead than the scorer read it.
+
+So the reply is a **strategy review**, never an edit. The rule is one sentence, and every refusal
+below enforces it:
+
+> No score and no position moves without the strategy version moving first.
+
+An ad-hoc override does not exist. The only way an item legitimately ranks higher is for a
+sentence in the rubric to say why it should, so the next scorer reaches the same answer.
+
+## The sequence
+
+1. **Note the version you are challenging.** `node <skill-scripts>/strategy.mjs validate` prints
+   `version N`. Keep `N`: it becomes `--from-version`, and it is what proves the rubric moved.
+2. **Write down the order before.** The candidate bead ids, highest first, comma-separated. This
+   is the baseline the diff is taken against.
+3. **Read the challenge back as a claim about one section.** Which section disagrees — the theme,
+   the value rule, the confidence rule, the effort anchor? Ask; do not guess.
+4. **Offer the interview.** Say plainly that the order is produced by the rubric, so a reorder
+   means a rubric change, and ask the questions in `SKILL.md` § Workflow, "Later runs".
+5. **Decide.** The rubric changes, or it stands. Both are legitimate outcomes; see below.
+6. **Re-rank** against the rubric as it now reads.
+7. **Record** the challenge on the bead, and show the owner what moved.
+
+## Outcome: the rubric changed
+
+Edit the sections the interview changed, then bump with the reason. A bump without a reason is
+refused, because a version that moved with no recorded reason is a change nobody can review.
+
+```bash
+node <skill-scripts>/strategy.mjs bump --reason "review turnaround is the theme now"
+```
+
+That writes the version, the date, and one change-log line. Then re-rank and record:
+
+```bash
+node <skill-scripts>/challenge.mjs record --bead agnt-ctx-abc.1 \
+  --challenge "the review queue should be above the installer fix" \
+  --resolution changed \
+  --reason "review turnaround is the theme now" \
+  --from-version 3 \
+  --before agnt-ctx-abc.1,agnt-ctx-abc.2,agnt-ctx-def.1 \
+  --after agnt-ctx-def.1,agnt-ctx-abc.1,agnt-ctx-abc.2 \
+  --out /tmp/challenge-entry.txt
+bd note agnt-ctx-abc.1 --file /tmp/challenge-entry.txt
+```
+
+`--out` writes the entry to a file, so the tracker appends it as data. Never paste the entry's own
+words into a shell string: the entry repeats what the human said, so a `"` in those words would end
+the quoting early and a `$(…)` would run a command. Pasting a **path** is safe instead —
+`bd note <bead> "$(cat <path>)"` reads the file and never parses the entry — but every example
+here uses `--file`, which needs no shell at all, so that is the one form to copy. `record` also
+prints the movement, which is what you show the owner:
+
+```
+[2026-12-01T09:30:00.000Z] [challenge] trail:2f9c4b1e7a3d5c60
+Outcome: done
+Evidence: challenged "the review queue should be above the installer fix"; strategy v3 → v4
+(updated 2026-12-01); rubric reason: review turnaround is the theme now; order 3 items, 2 moved:
+agnt-ctx-def.1 #3→#1, agnt-ctx-abc.1 #1→#2
+What is left: nothing — scores are re-ranked against strategy v4
+```
+
+## Outcome: no change to the rubric
+
+Valid, and common: the rubric already answers the challenge, or the owner decides the challenge
+does not outweigh the theme. The order does not move either — nothing changed that could move it.
+
+Record it anyway. An outcome that leaves no trace is a defect: the next session would rediscover
+the same challenge, and the owner would see the same question asked again.
+
+```bash
+node <skill-scripts>/challenge.mjs record --bead agnt-ctx-abc.1 \
+  --challenge "the review queue should be above the installer fix" \
+  --resolution no-change \
+  --reason "the value rule already requires a human gate, and the installer fix unblocks one" \
+  --from-version 3 \
+  --out /tmp/challenge-entry.txt
+bd note agnt-ctx-abc.1 --file /tmp/challenge-entry.txt
+```
+
+The entry carries the words that raised the challenge and the reasoning that answered it, under
+`Evidence`, so `bd show <bead>` recovers both. The strategy file is not touched.
+
+## The refusals
+
+`record` exits 1, writes nothing, and names the problem in four cases. Each is a shortcut worth
+refusing:
+
+| You tried | What it says |
+|---|---|
+| Reordered, rubric untouched | the order moved, but the strategy stayed at vN — a reorder without a rubric change |
+| "changed" with no bump | resolution "changed", but the version did not rise (v3 → v3) |
+| "no-change" after a bump | the version moved (v3 → v4), so the resolution is "changed" |
+| Challenged against a broken rubric | the strategy is not valid, so no score can be judged against it |
+
+`validate` adds a fifth, after the fact, and it needs one surviving entry: the newest change-log
+line must name the version the file carries, so a hand-raised version, or a bump whose log line was
+deleted, fails the next validation. The section is optional, so a log emptied of every entry passes
+— and `record` is what catches a silent reorder then, because it refuses an order that moved while
+the version stayed put.
+
+## How the order is computed
+
+The order is a plain list of candidate bead ids, highest first — from a scorer when one produced
+the queue, otherwise from re-reading the rubric yourself. `record` does not rank; it compares
+positions, which is what makes the movement deterministic and repeatable:
+
+- An id in both lists at a different position **moved**. Positions are 1-based, and the delta is
+  old minus new, so a positive delta is upward movement.
+- An id only in the new list is **new at** its position.
+- An id only in the old list **dropped from** its position.
+
+Moved items are reported in new-position order, then the arrivals, then the departures in
+old-position order. The same two lists therefore print the same clause every time.
+
+`--before` and `--after` are required for `changed`, because a recording that does not name what
+moved does not show the owner the consequence. They are optional for `no-change`, where they can
+only agree with each other — and are refused when they do not.
+
+## Where each record goes
+
+| Record | Lives in | Why |
+|---|---|---|
+| Why the rubric changed | the strategy file's change log, written by `bump` | a reviewer diffs it, and it is versioned next to the rubric |
+| The challenge, its reasoning and the movement | the bead trail, written by `bd note` from `record` | it is the progress record for that one bead, and a cold session reads it from `bd show` |
+
+Neither script writes to the other's store: `strategy.mjs` never calls the tracker, and
+`challenge.mjs` never edits the strategy file. A challenge recorded on a bead is not a rubric
+change, and a rubric change with no bead is not a challenge.

package/skills/workflow/prioritise-work/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: prioritise-work
+description: Sets, updates and validates the committed prioritisation strategy that bead scoring ranks against. Use when choosing what to work on next, when the strategy file is missing or stale, or when asked to "set the strategy".
+---
+
+# Prioritise Work
+
+Owns one artefact: the **strategy file**, the rubric a scorer reads before it judges a bead's reach, impact, confidence and effort. The skill interviews the owner to write or update it, and validates it before any scorer reads it.
+
+The strategy is a **committed file**, never a bead and never a scratch note. A rubric is reviewed, diffed and versioned as text; a bead carries progress and decisions about *work*, not the durable document that judges work. The tracker convention draws the same line: operational state — progress, decisions, refs — goes in the bead trail, and a document a reviewer diffs stays a file. Keep the strategy a file even when a bead could hold the same words, because then nobody can review a change to the rubric.
+
+## When to use
+
+- "What should I work on next?" — and there is no strategy file, or the one there is predates the current month.
+- "Set the strategy", "update the priorities", "we are optimising something else this month".
+- "This should be higher", "that is not the priority" — a challenge to the order, which is a strategy signal. See [CHALLENGE.md](CHALLENGE.md).
+- A scorer reports a score with no `strategyVersion`, or with one older than the file's.
+- Before ranking a backlog: the rubric has to be valid first.
+
+## When NOT to use
+
+- Shaping one feature — use `plan`; that skill scopes a feature, this one orders the work.
+- Recording an idea for later — use `record-idea`.
+- Tracker questions, or where a bead's state lives — use `bd-tool`.
+- Writing a PRD or a design document — use `write-a-prd`.
+
+## The strategy file
+
+| Item | Value |
+|---|---|
+| Default path | `.agent-cortex/working-docs/strategy.md`, relative to the repository root |
+| Override | `--file <path>` on every subcommand |
+| Contents | a version integer, a date, and five required sections |
+| Lifetime | committed; edited by interview, then versioned with `bump` |
+
+The working-docs root is the scratch directory the HITL handoff also uses: `.agent-cortex/working-docs/hitl/<bead-id>/handoff.md`. The strategy sits beside it and is the one file in that directory the repository commits.
+
+The default path resolves against the **repository root**, found by walking up for a `.git` entry, not against the directory the shell is in. Run `init` from any subdirectory and you still get the one strategy the repository owns. An override behaves differently: a relative `--file` resolves against the current directory, and an absolute one is taken as given.
+
+That directory's contents are usually ignored (`working-docs/*`), so track the strategy explicitly. Add the un-ignore line to the consuming repository's `.gitignore` once:
+
+```gitignore
+!.agent-cortex/working-docs/strategy.md
+```
+
+Use that rather than `git add -f`: an ignored file disappears from `git status`, so the next update is committed by nobody.
+
+## Workflow
+
+### First run — no strategy file
+
+1. Confirm the file is absent:
+
+```bash
+node <skill-scripts>/strategy.mjs validate
+```
+
+It exits 1 and names the path it looked for. Do not search the repository for an alternative: one strategy, one location, or two scorers rank against two rubrics.
+
+2. Write the shipped template to that path. This is the copy step — the script resolves its own template, so it works from either install layout:
+
+```bash
+node <skill-scripts>/strategy.mjs init
+```
+
+It stamps the date and leaves the version at `1`, and refuses to overwrite an existing file.
+
+3. Interview the owner. Ask one question at a time and write the answer under the section the table below names. Replace the guidance comment with the owner's own words; do not paraphrase a figure they gave.
+
+4. Validate before committing. `validate` prints the filled rubric to stdout only when it passes, and names every defective field or section on stderr otherwise:
+
+```bash
+node <skill-scripts>/strategy.mjs validate
+```
+
+5. Commit the file with the un-ignore line. The interview is finished only when `validate` exits 0 and `git ls-files --error-unmatch .agent-cortex/working-docs/strategy.md` succeeds.
+
+### Later runs — the file exists
+
+6. Read the current strategy and check its `**Updated:**` date. A date from an earlier month is stale: re-run the interview before scoring anything against it.
+
+7. Ask the four questions again, plus the confidence question, and edit the sections that changed. Leave a section alone when the answer has not changed.
+
+8. Bump the version and record the date and the reason, then validate:
+
+```bash
+node <skill-scripts>/strategy.mjs bump --reason "<why the rubric changed>"
+```
+
+The bump refuses a file that is not already valid and refuses an empty reason, raises the version by exactly one, writes today's date in UTC, and appends `- <date> v<n>: <reason>` to the change log. Report the old and new version to the owner.
+
+9. Commit the file. The version is what a score's `strategyVersion` points at, so a bump with no commit leaves scores pointing at a rubric nobody else has.
+
+### Interview questions
+
+One question produces one section. Ask them in this order; each answer is one to four lines.
+
+| Ask | Write into |
+|---|---|
+| What are you optimising this month? Name the outcome, not the feature. | `## Current themes` |
+| What must a bead change to be worth doing now? | `## What counts as value` |
+| When should a score be distrusted — which evidence is missing? | `## How to judge confidence` |
+| What are you deliberately not doing this month, however good it looks? | `## Explicitly out of scope` |
+| How long did comparable work take recently? Anchor the effort scale to it. | `## How to calibrate effort` |
+
+The confidence question matters as much as the other four: effort and impact estimates are judgements, and the strategy is the only place the owner states how far to trust one.
+
+## The scripts
+
+Two scripts, four subcommands, zero dependencies, no tracker access. `strategy.mjs` reads and writes the strategy file; `challenge.mjs` reads it and prints a trail entry. No run creates, tags or closes a bead.
+
+| Command | Behaviour | Exit |
+|---|---|---|
+| `init` | Writes the template, stamped with today's date; refuses an existing file | 0 written, 1 refused |
+| `validate` | Checks the version integer, the date, the change log and every required section; prints the file to stdout when valid | 0 valid, 1 invalid |
+| `bump` | Refuses an invalid file or an empty `--reason`, raises the version by one, records today, appends the change-log line | 0 bumped, 1 refused |
+| `record` (`challenge.mjs`) | Refuses an order or a resolution the strategy does not support; prints one bead-trail entry | 0 recorded, 1 refused |
+
+`validate` splits its output: status and errors go to stderr, the rubric goes to stdout. `validate > rubric.md` captures the rubric alone, which is how a scorer loads it. A failing run names the file and lists one line per defect, so one fix round clears the whole file.
+
+The date is checked as a **calendar** date, not as a shape. `2026-02-31` and `2026-04-31` fail in both `validate` and `--today`, because V8's ISO parser rolls them into the next month and accepts them; `2024-02-29` passes and `2026-02-29` does not. A rolled date records a change on a day it did not happen.
+
+Exit code 2 means a malformed call — an unknown subcommand or a bad `--today`. `--today YYYY-MM-DD` exists so a test pins the recorded date; a person accepts the default.
+
+## Hand edits and forgotten bumps
+
+A hand edit that changes a section but forgets `bump` still passes `validate`: the shape is intact, so nothing can tell the content moved. The protection is the version a score records — a scorer stores the `strategyVersion` it scored against, so a reader compares the two numbers and re-scores when they differ. The change log closes the rest of the gap: `validate` fails when its newest line names a version the header does not, so a raised version with no recorded reason is caught.
+
+## Red Flags
+
+- Red flag: moving the strategy into a bead, a label or a scratch file because it is "just a rubric".
+- Red flag: editing a strategy and skipping `bump`, or hand-raising the version, so the record hides the change.
+- Red flag: editing a score to satisfy a challenge, instead of changing the rubric that produced it.
+- Red flag: scoring against a file whose `validate` was never run — a malformed rubric scores silently.
+
+## Verification checklist
+
+- [ ] `node <skill-scripts>/strategy.mjs validate` exits 0 and printed the rubric, and every section carries the owner's words.
+- [ ] The version is one higher than the previous file for an update, or `1` for a new one, and the change log names it.
+- [ ] A challenged order moved only after a bump, and the record names what moved.
+- [ ] `git ls-files --error-unmatch .agent-cortex/working-docs/strategy.md` succeeds.
+- [ ] No bead was created, tagged or closed by this skill.
+
+## See Also
+
+- [CHALLENGE.md](CHALLENGE.md) — the sequence, the refusals and the no-change path when the order is challenged.
+- [plan](../../workflow/plan/SKILL.md) — shapes one feature into beads; this skill orders the beads that exist.
+- [bd-tool](../../productivity/bd-tool/SKILL.md) — where operational state lives, and why a durable document does not belong there.
+- [score-bead](../../workflow/score-bead/SKILL.md) — turns this rubric into a RICE record on a bead.
+- [hitl-collab](../../workflow/hitl-collab/SKILL.md) — the handoff document that shares the working-docs root with the strategy.