From 8d8ae8abfecf2ebb515b2e21c55dfd2f49b0d23d Mon Sep 17 00:00:00 2001 From: Ansho Rei Date: Sat, 22 Aug 2026 02:58:50 +0200 Subject: [PATCH] (822e8a1) Add a worklane-plan skill, and bump to 0.13.1 A third asset on the machinery 16c2bed settled, so the wiring is one entry in install::SKILLS. Four jobs, priorities, due dates, tags and campaigns, with propose-then-apply stated once at the top rather than per section. Every job writes to many tickets at once and no field can be cleared back to unset, so the document leans on the two traps that make a sweep destructive rather than merely wrong: set --tags replaces the whole field, and a due date is neither validated nor clearable. feature-planner-agent.md is deliberately not folded in. It decomposes a request into new tickets, which is intake; this orders the tickets that already exist, and one document holding both would fit neither. Co-Authored-By: Claude Opus 5 (1M context) --- AGENTS.md | 3 + Cargo.lock | 2 +- Cargo.toml | 2 +- README.md | 2 +- assets/PLAN.md | 182 +++++++++++++++++++++++++++++++++++++ src/install.rs | 38 +++++++- tests/cmd_install_skill.rs | 16 ++++ 7 files changed, 241 insertions(+), 4 deletions(-) create mode 100644 assets/PLAN.md diff --git a/AGENTS.md b/AGENTS.md index 630e545..0da8b17 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,6 +10,7 @@ - `src/install.rs` - the embedded agent assets and the compare-and-refuse install - `assets/SKILL.md` - the agent skill for the CLI itself, embedded with `include_str!` - `assets/REVIEW.md` - the agent skill for reviewing a finished ticket, shipped the same way. Assets are named after the role they teach; `SKILL.md` keeps its name because the role it teaches is the CLI +- `assets/PLAN.md` - the agent skill for grooming the whole board: priorities, due dates, tags and campaigns - `tests/` - Integration tests using `assert_cmd` and `assert_fs`, one file per command - Unit tests live beside the code in `#[cfg(test)] mod tests`, in `util.rs`, `handlers.rs` and `tui.rs` - Ticket files stored as `.md` in `.worklane//` directories @@ -178,6 +179,8 @@ and this file is for what someone changing worklane's own code needs. - **A refused document does not stop the ones behind it.** The loop reports an outcome per document and the "pick it up on their next session" line is printed once, and only when something was actually written - **A role skill is its own document, not a section of `SKILL.md`.** The frontmatter description is the whole of what decides whether a skill loads, and one description cannot name both "anything touching a ticket" and "only when a review is asked for" without fitting neither. It is also why the review document does not restate the CLI: it says to read the `worklane` skill too - The review skill's own rules are guarded by `the_review_skill_keeps_the_decisions_that_define_it`, because each of them is a line an edit could drop without breaking anything: **the reviewer never ticks a criterion** (a tick is the implementer's claim, unticking is the review disagreeing, and one mark for both loses the disagreement), **never moves the ticket** (`mv` belongs to whoever does the work, the reviewer's half is the recommendation), and **never reviews the working tree when no commit names the ticket** (it says what it searched for and stops, since an untraceable ticket in `reviewing` is itself the finding) +- **The plan skill is the one that can do damage, so its rules are the ones under test.** `set --tags` replaces the whole field, so a sweep that restates a ticket's tags incompletely deletes the rest, and a due date is neither validated nor clearable. `the_plan_skill_keeps_the_rules_that_bound_a_sweep` pins propose-then-apply and those two traps, because a document that loses them still reads like a plan +- `.opencode/agent/feature-planner-agent.md` is **deliberately not folded into `PLAN.md`**. It decomposes a feature request into new tickets, which is intake; `PLAN.md` orders the tickets that already exist. Merging them would give one document two jobs and a frontmatter description that fits neither, which is the same reason the review skill is its own document - `every_agent_facing_subcommand_is_documented` stays on `SKILL` alone. It owns the CLI surface; a role document uses the handful of commands its job needs, and requiring the rest would fill a review document with `init` and campaigns to satisfy a test. The two checks that do run over every document are the frontmatter and that no document shows a command that does not exist ### Color and Output diff --git a/Cargo.lock b/Cargo.lock index 040dab8..ae4ee10 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1494,7 +1494,7 @@ dependencies = [ [[package]] name = "worklane" -version = "0.13.0" +version = "0.13.1" dependencies = [ "anyhow", "assert_cmd", diff --git a/Cargo.toml b/Cargo.toml index 85caf99..65b42d1 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "worklane" -version = "0.13.0" +version = "0.13.1" edition = "2024" [dependencies] diff --git a/README.md b/README.md index 321b37c..9d787ef 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ Worklane is a local Kanban flow for agentic software development. | `worklane check [criterion]` | Ticks one acceptance criterion, by number as shown by `show` or by a substring. Prompts with the numbered list if omitted, or errors with it when there is no terminal | | `worklane uncheck [criterion]` | Unticks one acceptance criterion, addressed the same way | | `worklane comment ` | Adds a comment to a ticket by UUID or title | -| `worklane install-skill [skill]` | Writes the embedded agent skills to `~/.claude/skills//SKILL.md`, which Claude Code and opencode both read. Two ship: `worklane` teaches the CLI, `worklane-review` reviews a finished ticket against the code that claims to close it. Every document unless one is named. Leaves a modified copy alone unless `--force`; `--print` writes one to stdout instead and needs the name | +| `worklane install-skill [skill]` | Writes the embedded agent skills to `~/.claude/skills//SKILL.md`, which Claude Code and opencode both read. Three ship: `worklane` teaches the CLI, `worklane-review` reviews a finished ticket against the code that claims to close it, `worklane-plan` grooms the board as a whole, its priorities, due dates, tags and campaigns. Every document unless one is named. Leaves a modified copy alone unless `--force`; `--print` writes one to stdout instead and needs the name | ## Exit codes | Code | Meaning | diff --git a/assets/PLAN.md b/assets/PLAN.md new file mode 100644 index 0000000..29ce6e1 --- /dev/null +++ b/assets/PLAN.md @@ -0,0 +1,182 @@ +--- +name: worklane-plan +description: Groom a worklane board as a whole rather than one ticket at a time: review whether the priorities are right relative to each other, plan work by setting due dates, check the tags for consistency, and find the tickets that belong together in a campaign. Use for questions about the backlog as a body of work, what to do next week, what is mis-prioritised or mis-tagged, and what could become one goal. Not for filing or working a single ticket. +--- + +# Planning a worklane board + +For "are the backlog priorities right", "plan in tickets for next week", "check the +tagging", "which of these could be one campaign". The subject is the board, not a +ticket. Filing one, working one and reviewing one are other jobs. + +The CLI itself is the `worklane` skill: the statuses, how a ticket is addressed and +which command owns which field. Read it too. This document is the judgement. + +## The one rule + +**Propose the whole set of edits, wait, then apply exactly what was approved.** + +Every job here writes to many tickets at once, and no field can be cleared back to unset +yet, so a due date written by mistake can only be overwritten with another guess. A wrong +edit to one ticket is a mistake; a wrong sweep is thirty of them with no undo. So a +proposal is a list, one line per intended edit, each naming the ticket and the command +that would make it: + +``` +(1b78a24) priority 3 -> 1 worklane set 1b78a24 --priority 1 +(4179958) due -> 2026-08-29 worklane set 4179958 --due 2026-08-29 +``` + +Then apply what was approved and nothing else. Not "and a few obvious ones while I was +there": an approval is for the list that was shown. + +## Who writes what + +Every field has exactly one command that writes it, and a sweep that reaches for any +other way is editing the file by hand: + +| Field | Writer | +|-------|--------| +| Priority, Due, Tags | `worklane set --priority` / `--due` / `--tags` | +| Relations | `worklane relate --blocked-by` / `--regression-of` / `--relates-to` | +| Campaign membership | `worklane assign ` | +| Owner | `worklane chown ` | +| Status | `worklane mv --status ` | + +**Never edit a ticket file directly.** The filename, the `Status` field and the directory +have to agree, and the commands are what keep them agreeing. A hand-written Relations +line is worse still: it is the one section read back by machine, and a target that does +not resolve to a uuid is an error on every later read of that ticket. + +The last two rows are in the table to be recognised, not used. See the closing section. + +## Read the board first + +``` +worklane ls # every status, counts then tickets +worklane ls backlog # one status +worklane ls --priority 1 # the top of the pile +worklane show 1b78a24 # one ticket, with its relations and comments +worklane campaign ls # the goals that already exist +``` + +`ls` prints the mark, the id, the title, the owner and the due date. It does **not** +print tags, and there is no tag filter yet, so any judgement about tags means reading the +tickets themselves. On a board of a few dozen that is a `show` per ticket and is worth +doing rather than guessing from titles. + +Read `done` too when the question is about what to do next. What was finished last is the +best evidence of what this board actually moves at, and a plan that ignores it is a wish. + +## Priorities + +Priority runs **1 most urgent to 5 least**, and may be unset. `worklane set +--priority ` is the only writer. + +Priority is relative. A ticket is never urgent by itself, it is urgent above something +else, so every proposed change has to name what it now sits above and below. "This looks +important" is not a reason; "this blocks three tickets that are all dated before it" is. + +What to look for: + +- **A blocker priced below what it blocks.** Read the Relations. A ticket that others are + `blocked by` cannot be less urgent than the most urgent of them, or the board is asking + for work in an order it will not allow. +- **A flat board.** If almost everything is 3, the field is carrying no information and + the answer is not to renumber everything at once. Propose the few that are genuinely 1 + and the few that are genuinely 5, and leave the middle alone. +- **Too many 1s.** If everything is urgent, nothing is. Say how many there are before + proposing another. +- **A low priority already in `committed`.** Either the priority is wrong or starting it + was, and which one it is decides whether the fix is a `set` or a conversation. +- **A priority nobody has touched since the ticket was filed.** It is the filer's first + guess, not a decision. That is the pile worth reading. + +## Due dates + +`worklane set --due 2026-08-29`, format `YYYY-MM-DD`. + +**The value is not validated.** A typo is stored as written rather than refused, and it +cannot be cleared afterwards, only replaced. Write it once, carefully, and read it back +with `show`. + +Ask the system what today is rather than assuming it. A plan built on a guessed date is +wrong by however much the guess was wrong. + +The rules a dating plan has to keep: + +- **Nothing is dated before the ticket it is blocked by.** Read the Relations first and + date blockers ahead of their dependents. A dependent dated before its blocker is a date + `mv` will refuse to honour anyway. +- **A blocker left undated makes its dependent's date a fiction.** Either date both or + neither. +- **Date what fits, not what exists.** Ask how much capacity the week holds, or take the + answer from what `done` shows the board finishing in a comparable stretch. Dating the + whole backlog produces a board where every ticket is late, which is the same as no + dates at all. +- **Do not date `done`.** It is finished; a date on it is noise in every listing. +- Leave the rest unset. An unset due date is honest about what has not been planned. + +## Tags + +`worklane set --tags bug,cli` is the writer, and it **replaces the whole +field**. Restate every tag the ticket should keep, or the ones you left out are gone. +This is the single most destructive thing in this document. + +Derive the vocabulary from the board rather than inventing one. Read the tickets, count +what is actually used, and show the count before proposing anything. What to report: + +- **Two spellings of one idea.** `bug` and `bugfix`, `tui` and `ui`. Pick the one already + used more and say so. +- **A tag used exactly once.** Either it is the start of a category and should be applied + to its siblings, or it is a private note and should go. Do not leave it as it is without + saying which. +- **A tag that restates a field.** A `p1` tag beside a Priority field, an `open` tag + beside a Status, an owner's name as a tag. The field is the writer; the tag is a copy + that will disagree with it. This board already made that mistake once with priority and + undid it deliberately. +- **An untagged ticket** in a board where everything else is tagged. It is invisible to + every question asked by tag. + +Tags are for kind, not for state and not for goal. State is the status directory and the +fields; a goal is a campaign. + +## Campaigns + +``` +worklane campaign ls +worklane campaign show "v1 release" +worklane campaign add --title "..." --description "..." +worklane assign "v1 release" 1b78a24 +``` + +A campaign is the tickets that have to be finished **together** for one outcome. The test +is whether you can name the outcome in a single line without listing the members. "The +tui is usable on a narrow terminal" is a campaign. "The tui tickets" is a tag. + +- **Do not group by tag.** Ten tickets tagged `bug` share a kind, not a goal, and putting + them in a container says nothing that the tag did not already say. +- **Check what exists first.** `campaign ls` before proposing a new one, or you will + propose a second container for a goal that already has one. +- **A ticket is in at most one campaign**, and `assign` moves it rather than adding a + second. So two proposed campaigns that overlap are really one proposal to take members + out of the other, and it has to say so. +- **A campaign's state is derived**, open until every member is done. There is nothing to + close and nothing to move. A campaign whose members are all done is finished already. +- `assign` takes the **campaign first and the ticket second**, like `chown`. + +Proposing a campaign means naming the goal, the members, and what is deliberately left +out of it. The last part is what makes it a goal rather than a pile. + +## What a planner does not touch + +- **Descriptions, acceptance criteria and implementation plans.** They are the ticket + author's account of the work, and grooming is about how the work is ordered, not what + it is. Something wrong in there is a comment on that ticket. +- **Status.** `mv` belongs to whoever does the work. A plan that moves tickets between + columns is reporting progress that did not happen. +- **Owner.** `chown` records a commitment a person made. Propose it, do not write it, + unless you were asked to assign the work. +- **New tickets.** Grooming is about what is on the board. Something genuinely missing is + worth filing, by the rules in the `worklane` skill, but say it is a new ticket rather + than folding it into a grooming sweep. diff --git a/src/install.rs b/src/install.rs index 7ac0928..4b42d69 100644 --- a/src/install.rs +++ b/src/install.rs @@ -54,11 +54,24 @@ pub const REVIEW_SKILL: Asset = Asset { content: include_str!("../assets/REVIEW.md"), }; +/// The skill that grooms the board as a whole rather than a ticket at a time. +/// +/// Its own document for the reason `REVIEW_SKILL` is: it is wanted for questions about +/// the backlog as a body of work, and loading it for every ticket touched would be a +/// description that fits nothing. It is also the document where the destructive edits +/// live, since every job in it writes to many tickets at once. +pub const PLAN_SKILL: Asset = Asset { + name: "worklane-plan", + what: "skill", + relative: "worklane-plan/SKILL.md", + content: include_str!("../assets/PLAN.md"), +}; + /// Every skill this binary carries, in the order they install. /// /// A `static` rather than a `const` so the slice borrowed from it outlives the /// statement that took it: a `const` is inlined at each use and the borrow dies there. -pub static SKILLS: [Asset; 2] = [SKILL, REVIEW_SKILL]; +pub static SKILLS: [Asset; 3] = [SKILL, REVIEW_SKILL, PLAN_SKILL]; /// The skill a name on the command line asks for. pub fn skill_named(name: &str) -> Result<&'static Asset> { @@ -363,6 +376,29 @@ mod tests { } } + /// The rules that keep a grooming sweep from being a silent rewrite of the board. + /// + /// Every one of these is a line an edit could drop while leaving a document that + /// still reads like a plan: `set --tags` replacing the whole field is how thirty + /// tickets quietly lose their tags, and propose-then-apply is the only thing + /// standing between a wrong judgement and thirty wrong tickets. + #[test] + fn the_plan_skill_keeps_the_rules_that_bound_a_sweep() { + for required in [ + "Propose the whole set of edits", + "replaces the whole\nfield", // `set --tags` is the destructive one + "not validated", // and a due date cannot be taken back + "blocked by", // ordering constrains any dating plan + "worklane campaign ls", + "does not touch", + ] { + assert!( + PLAN_SKILL.content.contains(required), + "the plan skill no longer says {required:?}" + ); + } + } + /// The decisions that make the review document a review rather than a rewrite. /// /// Each of these is a rule an edit would drop without breaking anything else: a diff --git a/tests/cmd_install_skill.rs b/tests/cmd_install_skill.rs index 467d881..fca9995 100644 --- a/tests/cmd_install_skill.rs +++ b/tests/cmd_install_skill.rs @@ -7,6 +7,7 @@ const BIN_NAME: &str = env!("CARGO_BIN_EXE_worklane"); /// files in the repo rather than to a description of them. const SKILL: &str = include_str!("../assets/SKILL.md"); const REVIEW: &str = include_str!("../assets/REVIEW.md"); +const PLAN: &str = include_str!("../assets/PLAN.md"); /// `HOME` is redirected, so the suite never writes into the home of whoever runs it. /// A temp directory rather than the real one is also what makes the already-installed @@ -25,6 +26,10 @@ fn installed_review(home: &TempDir) -> std::path::PathBuf { home.path().join(".claude/skills/worklane-review/SKILL.md") } +fn installed_plan(home: &TempDir) -> std::path::PathBuf { + home.path().join(".claude/skills/worklane-plan/SKILL.md") +} + /// Nothing about the skills needs a board, and they are wanted before there is one. /// /// One invocation writes every document. A person who learned the command before the @@ -42,8 +47,11 @@ fn every_skill_installs_outside_a_worklane_directory() { assert!(stdout.contains(".claude/skills/worklane/SKILL.md"), "{stdout}"); assert!(stdout.contains("Installed the worklane-review skill"), "{stdout}"); assert!(stdout.contains(".claude/skills/worklane-review/SKILL.md"), "{stdout}"); + assert!(stdout.contains("Installed the worklane-plan skill"), "{stdout}"); + assert!(stdout.contains(".claude/skills/worklane-plan/SKILL.md"), "{stdout}"); assert_eq!(std::fs::read_to_string(installed(&home)).unwrap(), SKILL); assert_eq!(std::fs::read_to_string(installed_review(&home)).unwrap(), REVIEW); + assert_eq!(std::fs::read_to_string(installed_plan(&home)).unwrap(), PLAN); // Once, not per document: it is the one thing to do next, not part of an outcome. assert_eq!( @@ -64,6 +72,7 @@ fn a_named_skill_installs_only_that_one() { assert_eq!(out.status.code(), Some(0), "{stdout}"); assert_eq!(std::fs::read_to_string(installed_review(&home)).unwrap(), REVIEW); assert!(!installed(&home).exists(), "a named install wrote the other document too"); + assert!(!installed_plan(&home).exists(), "a named install wrote the other document too"); } /// A name nothing ships is a stop, with the choices in the message: guessing at the @@ -80,6 +89,7 @@ fn an_unknown_skill_name_is_refused_and_lists_what_there_is() { assert!(stderr.contains("worklane-review"), "{stderr}"); assert!(!installed(&home).exists()); assert!(!installed_review(&home).exists()); + assert!(!installed_plan(&home).exists()); } #[test] @@ -138,6 +148,7 @@ fn a_modified_copy_does_not_stop_the_other_documents() { assert!(stdout.contains("install-skill worklane --print"), "{stdout}"); assert_eq!(std::fs::read_to_string(installed(&home)).unwrap(), "hand written\n"); assert_eq!(std::fs::read_to_string(installed_review(&home)).unwrap(), REVIEW); + assert_eq!(std::fs::read_to_string(installed_plan(&home)).unwrap(), PLAN); } /// The print path is what makes a modified copy diffable, so it has to be the document @@ -154,8 +165,13 @@ fn print_writes_the_named_document_to_stdout_and_installs_nothing() { assert_eq!(out.status.code(), Some(0)); assert_eq!(String::from_utf8_lossy(&out.stdout), REVIEW); + let out = run(&home, &["install-skill", "worklane-plan", "--print"]); + assert_eq!(out.status.code(), Some(0)); + assert_eq!(String::from_utf8_lossy(&out.stdout), PLAN); + assert!(!installed(&home).exists(), "--print installed the skill anyway"); assert!(!installed_review(&home).exists(), "--print installed the skill anyway"); + assert!(!installed_plan(&home).exists(), "--print installed the skill anyway"); } /// A diff is against one document. Printing them all run together would be neither of