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