diff --git a/AGENTS.md b/AGENTS.md index 2db9416..630e545 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,7 +8,8 @@ - `src/campaign.rs` - the campaign file format, its resolution, its index and its members - `src/tui.rs` - board state, the change digest, and the ratatui draw - `src/install.rs` - the embedded agent assets and the compare-and-refuse install -- `assets/SKILL.md` - the agent skill `install-skill` ships, embedded with `include_str!` +- `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 - `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 @@ -170,7 +171,14 @@ and this file is for what someone changing worklane's own code needs. - **A modified copy is refused, not overwritten.** Someone may have edited it on purpose, and the message names `--print` so it can be diffed and `--force` so it can be replaced. A read error is not treated as absent either: the write reports the real reason - Three tests guard the document rather than the mechanism, and they are the ones that earn their keep: the frontmatter has to parse (both agents silently ignore a document without it), every `worklane ` the skill shows has to be a real subcommand, and every subcommand outside `NOT_FOR_AGENTS` has to appear in the skill. The last one catches a new command that nothing tells an agent about - `install-skill` looks for no board. The skill is what teaches an agent worklane, so needing a `.worklane` to install it would put it out of reach exactly when it is wanted -- The assets under `.opencode/` are the user's, not this repo's to ship. Do not embed or install them +- The assets under `.opencode/` are the user's, not this repo's to ship. Do not embed or install them. `reviewing-agent.md` there is the prior art the review skill grew out of and is deliberately **left in place**: its content is now in `assets/REVIEW.md`, but deleting a file under `.opencode/` is not this repo's call. Whether the stale copies there go is b2c5531's question +- **`install-skill` writes every shipped document, and the name narrows it.** One document teaches the CLI and the others teach a job done with it, so a person who learned the invocation before a document existed still receives it. Requiring a name per document would mean a new skill silently never arrives for anyone who does not read the changelog +- **`--print` requires the name.** It exists so a modified copy can be diffed, and a diff is against one document; printing them concatenated would be neither of them. The unnamed case errors with the list of names rather than guessing, the same choice the `comment --` body makes +- The refusal message names the document it is about, `install-skill worklane --print`, since with several installed "compare with --print" does not say compare what +- **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) +- `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 - Use `color_text()` for coloured output — it respects `should_use_colors()` (terminal detection), and `paint()` is the same with the decision passed in diff --git a/Cargo.lock b/Cargo.lock index f0adbe5..040dab8 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1494,7 +1494,7 @@ dependencies = [ [[package]] name = "worklane" -version = "0.12.1" +version = "0.13.0" dependencies = [ "anyhow", "assert_cmd", diff --git a/Cargo.toml b/Cargo.toml index ea4d64b..85caf99 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "worklane" -version = "0.12.1" +version = "0.13.0" edition = "2024" [dependencies] diff --git a/README.md b/README.md index 0c2a991..321b37c 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` | Writes the embedded agent skill to `~/.claude/skills/worklane/SKILL.md`, which Claude Code and opencode both read. Leaves a modified copy alone unless `--force`; `--print` writes it to stdout instead | +| `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 | ## Exit codes | Code | Meaning | diff --git a/assets/REVIEW.md b/assets/REVIEW.md new file mode 100644 index 0000000..ffab9f8 --- /dev/null +++ b/assets/REVIEW.md @@ -0,0 +1,160 @@ +--- +name: worklane-review +description: Review a finished worklane ticket against the code that claims to close it, and record the verdict on the board. Use when asked to review a ticket, to check whether a ticket is really done, or to verify that an implementation matches its acceptance criteria, whether the ticket is named by id, by title or as "the one in reviewing". Covers finding the commits, judging each criterion against the code, and what a reviewer may and may not write back to the board. +--- + +# Reviewing a worklane ticket + +For "review ticket 1b78a24", "is 4179958 actually done", "check the work on the tui +scroll ticket". The subject is one ticket. Reviewing a diff that no ticket claims is +ordinary code review and not this job. + +This document is the review only. The CLI itself, the statuses, how a ticket is +addressed and the argument traps, is the `worklane` skill; read that too. + +## What a review produces + +Three things, in this order, and nothing else: + +1. **One comment** on the ticket, in the structure below. +2. **Unticked criteria**, for the ones the code does not actually meet. +3. **Appended criteria**, for work the review found that the ticket never asked for. + +You do not tick a criterion, you do not move the ticket, and you do not fix the code. +Each of those has a reason, given where it comes up. + +## 1. Read the ticket before the code + +``` +worklane show 1b78a24 +``` + +All of it, comments included. The description says what was wrong, the criteria say what +"done" was supposed to mean, the plan says what someone intended to do about it, and the +comments are where the intent moved after filing. A criterion that contradicts a comment +is one of the more useful things you can find: it means the ticket was not updated when +the plan changed, and one of the two is now lying to whoever reads the board. + +Read the Relations too. A `blocked by` that is not done, or a `regression of`, changes +what the change was allowed to do and what the review has to check twice. + +## 2. Find the work + +The board stores no branch and no sha, so the link from ticket to code has to be found. +Check the repo's own commit convention first, in its `AGENTS.md`, `CLAUDE.md` or in +`git log`, rather than assuming the id appears in the message at all. + +``` +git log --all --oneline --grep 1b78a24 # where commits name the ticket +git log --oneline -20 # where they do not, read the recent ones +git branch -a --list '*scroll*' # a branch named after the work +git diff main...HEAD # the whole change, once you have both ends +``` + +Widen it with the files the description names, since a ticket that names +`src/tui.rs` is reviewable through `git log -p -- src/tui.rs` even when no commit +message mentions it. + +**If nothing names the ticket, that is the finding.** Do not review the working tree on +the assumption that whatever is uncommitted must be the work, and do not report a pass +you could not check. Comment what you searched for and stop: a ticket sitting in +`reviewing` with no traceable work is exactly what a reviewer is for. + +## 3. Judge each criterion separately + +One criterion at a time, by its number from `show`, and each against **the code**. Never +against the implementation plan: the plan is what someone meant to do, and a review that +confirms the plan was followed cannot notice that following it was not enough. + +Read the code the criterion is about, not only the lines the diff touched. A criterion +that the diff satisfies and the surrounding code defeats is not met. + +Give each one a verdict and its evidence, a file and a line: + +- **met** - and where. +- **not met** - and what is missing. +- **cannot tell** - and what would settle it. This is a real verdict. Use it instead of + guessing, and say what you would have to run or read. + +Run whatever the repo runs, its test suite and its linter. A suite that fails is not a +criterion, but no criterion is met while it fails. + +Then the two questions the criteria cannot ask themselves: + +- **What did this change break that no criterion covers?** Silent behaviour changes, + a message or exit code something else reads, an edge case the ticket never named. +- **What did the ticket never think of?** That is what you append in step 5. + +## 4. Write one comment + +One call, one comment. Not one per criterion: the board renders comments in the order +they were written, and a review split over eight of them cannot be read as a verdict. + +``` +worklane comment 1b78a24 "**Verdict**: two criteria unmet, the scroll clamp is off by the header + +**Work reviewed**: 4edc7fa, 6d327df on master + +**Criteria** +1. met - PageUp and PageDown reach detail_scroll, src/tui.rs:412 +2. not met - the footer still lists the arrow keys, src/tui.rs:88 +3. cannot tell - no test covers a ticket longer than the viewport + +**Findings** +- The clamp uses the raw line count, so a wrapped ticket scrolls past its end, src/tui.rs:430 +- Unticked criterion 2 accordingly + +**Recommendation**: back to committed, the clamp is the ticket's own subject" +``` + +Keep the structure, drop the sections that have nothing in them. `**Work reviewed**` is +never empty: it holds the shas, the branch, or what you searched for and did not find. +Write for the person who has to act on it, so every finding says where it is. + +The comment body takes a leading hyphen without being parsed as a flag, so a finding can +quote `--force` literally. A body of exactly `--` needs its own separator. + +## 5. Write the verdict back to the ticket + +``` +worklane uncheck 1b78a24 2 +worklane append 1b78a24 --acceptance "The footer lists only the keys that are bound" +``` + +Untick every criterion you found unmet, one call each, by the number `show` printed. Do +it after the comment so there is a written reason on the board before the mark changes. + +**Never tick a criterion.** A tick is the implementer's claim that something is done, and +unticking is the review disagreeing with that claim. A reviewer that also ticks makes +both the same mark, and the board stops recording that anyone ever disagreed. A criterion +you found met but left unticked is a line in the comment, not a mark for you to fix. + +Append a criterion only for work the next commit has to make true, phrased so it can be +ticked off. Advice, praise and anything already covered by an existing criterion belong in +the comment. An appended criterion that restates a finding just makes the ticket longer +without making it clearer. + +**Do not move the ticket.** `mv` belongs to whoever does the work, the same way ticking +does. Your half is the recommendation in the comment; acting on it is theirs. A reviewer +that reviews and closes in one breath leaves nobody to disagree with. + +## What a reviewer does not touch + +- **The description, plan, title, priority and tags.** Rewriting the ticket you are + reviewing destroys the record of what was asked for, which is the only thing your + verdict can be measured against. Say it in the comment. +- **The code.** Even a one-line fix is a finding: whoever wrote it gets to make the + change, and gets to keep the review that asked for it. Fix it only if you are asked to, + and then it is a new piece of work with its own comment. +- **Another ticket's business.** Something you found that is genuinely out of scope gets + its own ticket, filed the way the `worklane` skill says, and + `worklane relate --relates-to ` so the two are findable from each other. + +## Reviewing what is waiting + +``` +worklane ls reviewing +``` + +One ticket at a time, with its own comment. A single comment covering four tickets lands +on one of them and is lost to the other three. diff --git a/src/command.rs b/src/command.rs index 81397e9..8e9a50e 100644 --- a/src/command.rs +++ b/src/command.rs @@ -185,8 +185,15 @@ pub enum Command { ticket: String, }, - /// Install the agent skill that teaches an agent to use worklane + /// Install the agent skills that teach an agent to use worklane + /// + /// Every shipped document by default. The optional name narrows it to one, and + /// `--print` requires it: a diff is against one document, and printing them all + /// concatenated would only look like one. InstallSkill { + /// Skill to install or print, all of them if omitted + skill: Option, + /// Overwrite an existing copy that has been modified #[arg(long)] force: bool, diff --git a/src/handlers.rs b/src/handlers.rs index 31cb983..21498a3 100644 --- a/src/handlers.rs +++ b/src/handlers.rs @@ -1191,33 +1191,61 @@ pub fn cmd_check(args: &CheckArgs, checked: bool, start: &Path) -> Result<()> { Ok(()) } -/// Install the agent skill, or print it so a modified copy can be diffed. +/// Install the agent skills, or print one so a modified copy can be diffed. /// -/// No board is looked for. The document is what teaches an agent worklane, so needing -/// a `.worklane` to install it would put it out of reach exactly when it is wanted. -pub fn cmd_install_skill(force: bool, print: bool) -> Result<()> { +/// No board is looked for. The documents are what teach an agent worklane, so needing +/// a `.worklane` to install them would put them out of reach exactly when they are +/// wanted. +/// +/// With no name, every shipped document is installed. Narrowing to one is the +/// exception rather than the rule, so that a document added in a later version reaches +/// anyone who already knows the command. +pub fn cmd_install_skill(skill: Option<&str>, force: bool, print: bool) -> Result<()> { if print { - print!("{}", install::SKILL.content); + // Printing every document would run them together into something that is not + // any of them, and the point of `--print` is to diff one against its copy. + let name = skill.ok_or_else(|| { + anyhow!( + "name the skill to print, as in `worklane install-skill worklane --print`. This binary ships {}", + install::skill_names() + ) + })?; + print!("{}", install::skill_named(name)?.content); return Ok(()); } + let chosen: Vec<&install::Asset> = match skill { + Some(name) => vec![install::skill_named(name)?], + None => install::SKILLS.iter().collect(), + }; + let root = install::skills_root()?; - match install::SKILL.install(&root, force)? { - install::Outcome::Written(path) => { - println!("Installed the worklane {} to: {}", install::SKILL.what, path.display()); - println!("Claude Code and opencode pick it up on their next session"); - } - install::Outcome::Unchanged(path) => { - println!("Already up to date: {}", path.display()); - } - install::Outcome::Refused(path) => { - println!("Differs from the version in this binary: {}", path.display()); - println!( - "Compare with `worklane install-skill --print`, or overwrite with --force" - ); + let mut written = false; + for asset in chosen { + match asset.install(&root, force)? { + install::Outcome::Written(path) => { + println!("Installed the {} {} to: {}", asset.name, asset.what, path.display()); + written = true; + } + install::Outcome::Unchanged(path) => { + println!("Already up to date: {}", path.display()); + } + install::Outcome::Refused(path) => { + println!("Differs from the version in this binary: {}", path.display()); + println!( + "Compare with `worklane install-skill {} --print`, or overwrite with --force", + asset.name + ); + } } } + // Once, and only when something arrived: repeating it per document would make the + // instruction look like part of each outcome rather than the one thing to do next. + if written { + println!("Claude Code and opencode pick it up on their next session"); + } + Ok(()) } diff --git a/src/install.rs b/src/install.rs index 97917e6..7ac0928 100644 --- a/src/install.rs +++ b/src/install.rs @@ -1,13 +1,18 @@ //! Shipping the agent assets with the binary. //! -//! The skill document lives at `assets/SKILL.md` in this repo and is embedded with +//! The skill documents live in `assets/` in this repo and are embedded with //! `include_str!` rather than copied by an install script, because `cargo install` -//! places binaries and nothing else. Embedding means the document can never be a +//! places binaries and nothing else. Embedding means a document can never be a //! different version from the binary it describes, and there is no second file to //! lose track of. //! -//! The machinery is written once for both assets this repo will ship. The tool file -//! for opencode is executable code needing Bun, so it gets its own command and its +//! `SKILLS` is every skill the binary carries, and `install-skill` writes all of them. +//! One document teaches the CLI and the others teach a job done with it; a person who +//! has learned the invocation should not have to learn a new name for each document +//! added later, or the new one silently never arrives. +//! +//! The machinery is written once for both kinds of asset this repo will ship. The tool +//! file for opencode is executable code needing Bun, so it gets its own command and its //! own root, but the compare-and-refuse logic is the same and lives here. use std::io; @@ -17,6 +22,9 @@ use anyhow::{Result, anyhow}; /// One thing the binary carries and can write into a user's agent configuration. pub struct Asset { + /// How it is addressed on the command line. For a skill this is also its directory + /// and its frontmatter `name:`, which both agents require to agree. + pub name: &'static str, /// What it is called in messages, e.g. `skill`. pub what: &'static str, /// Where it goes under its root, e.g. `worklane/SKILL.md`. @@ -24,13 +32,50 @@ pub struct Asset { pub content: &'static str, } -/// The skill document, as of the commit this binary was built from. +/// The skill that teaches the CLI, as of the commit this binary was built from. pub const SKILL: Asset = Asset { + name: "worklane", what: "skill", relative: "worklane/SKILL.md", content: include_str!("../assets/SKILL.md"), }; +/// The skill that reviews a finished ticket against the code that claims to close it. +/// +/// A document of its own rather than a section of `SKILL`, because it is loaded for a +/// different job: the CLI skill is wanted for anything touching a ticket, and this is +/// wanted only when a review is asked for. One document holding both would be loaded +/// constantly to say nothing, and the frontmatter description, which is the whole of +/// what decides the loading, cannot describe two jobs without fitting neither. +pub const REVIEW_SKILL: Asset = Asset { + name: "worklane-review", + what: "skill", + relative: "worklane-review/SKILL.md", + content: include_str!("../assets/REVIEW.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]; + +/// The skill a name on the command line asks for. +pub fn skill_named(name: &str) -> Result<&'static Asset> { + SKILLS.iter().find(|asset| asset.name == name).ok_or_else(|| { + anyhow!("no skill named {name:?}. This binary ships {}", skill_names()) + }) +} + +/// The names, for the errors that have to say what there is to choose from. +pub fn skill_names() -> String { + SKILLS + .iter() + .map(|asset| asset.name) + .collect::>() + .join(", ") +} + /// Where a skill has to sit to be found, for both agents worklane is used from. /// /// One path serves both. Claude Code reads `~/.claude/skills//SKILL.md`, and @@ -157,29 +202,53 @@ mod tests { } #[test] - fn the_skill_lands_where_both_agents_look_for_it() { + fn every_skill_lands_where_both_agents_look_for_it() { let root = skills_root().unwrap(); assert!(root.ends_with(".claude/skills"), "{}", root.display()); - assert!( - SKILL.path(&root).ends_with(".claude/skills/worklane/SKILL.md"), - "{}", - SKILL.path(&root).display() - ); + + for asset in &SKILLS { + let path = asset.path(&root); + assert!( + path.ends_with(format!(".claude/skills/{}/SKILL.md", asset.name)), + "{}", + path.display() + ); + } + } + + /// Two documents that install to one path means the second silently replaces the + /// first, and only whichever is listed last is ever read. A copy-pasted `relative` + /// is exactly how that happens. + #[test] + fn no_two_shipped_skills_share_a_name_or_a_path() { + for (index, asset) in SKILLS.iter().enumerate() { + for other in &SKILLS[index + 1..] { + assert_ne!(asset.name, other.name); + assert_ne!(asset.relative, other.relative); + } + } } #[test] - fn the_embedded_skill_has_usable_frontmatter() { + fn every_embedded_skill_has_usable_frontmatter() { // Guards the whole shipping mechanism: without frontmatter, or under a name // that does not match its directory, both agents ignore the document and // nothing else would notice. - assert_eq!(frontmatter_field(SKILL.content, "name").as_deref(), Some("worklane")); + for asset in &SKILLS { + assert_eq!( + frontmatter_field(asset.content, "name").as_deref(), + Some(asset.name), + "the frontmatter name has to match the directory it installs into" + ); - let description = - frontmatter_field(SKILL.content, "description").expect("a description to trigger on"); - assert!( - description.len() > 80, - "the description is what decides whether the skill loads at all" - ); + let description = frontmatter_field(asset.content, "description") + .unwrap_or_else(|| panic!("{} ships without a description to trigger on", asset.name)); + assert!( + description.len() > 80, + "{}: the description is what decides whether the skill loads at all", + asset.name + ); + } } /// Every code span and fenced-block line, which is where commands live. @@ -209,7 +278,7 @@ mod tests { } #[test] - fn the_embedded_skill_only_names_commands_that_exist() { + fn no_embedded_skill_names_a_command_that_does_not_exist() { // Taken from clap rather than written out here. A hand-maintained list is the // very drift this test exists to catch. use clap::CommandFactory; @@ -220,25 +289,34 @@ mod tests { known.push("--help".to_string()); known.push("--version".to_string()); - let mut checked = 0; - for snippet in code_snippets(SKILL.content) { - let mut words = snippet.split_whitespace(); - // Only a snippet that *starts* with worklane is a command being shown. - if words.next() != Some("worklane") { - continue; + let mut total = 0; + for asset in &SKILLS { + let mut checked = 0; + for snippet in code_snippets(asset.content) { + let mut words = snippet.split_whitespace(); + // Only a snippet that *starts* with worklane is a command being shown. + if words.next() != Some("worklane") { + continue; + } + let Some(candidate) = words.next() else { continue }; + // A flag before the subcommand, as in the `mv -- -leading-title` example. + if candidate.starts_with("--") && !known.iter().any(|k| k == candidate) { + continue; + } + checked += 1; + assert!( + known.iter().any(|k| k == candidate), + "{} shows `worklane {candidate}`, which is not a subcommand", + asset.name + ); } - let Some(candidate) = words.next() else { continue }; - // A flag before the subcommand, as in the `mv -- -leading-title` example. - if candidate.starts_with("--") && !known.iter().any(|k| k == candidate) { - continue; - } - checked += 1; - assert!( - known.iter().any(|k| k == candidate), - "the skill shows `worklane {candidate}`, which is not a subcommand" - ); + // A skill that shows no command at all is either not about worklane or has + // had its examples emptied out, and either way the check above passed on + // nothing. + assert!(checked > 0, "{} shows no worklane command at all", asset.name); + total += checked; } - assert!(checked > 8, "expected the skill to show commands, checked only {checked}"); + assert!(total > 8, "expected the skills to show commands, checked only {total}"); } /// Subcommands the skill has no business teaching: the board is interactive and @@ -248,6 +326,11 @@ mod tests { /// The converse, and the one that goes stale on its own: a *new* subcommand absent /// from the skill is invisible to an agent, and nothing else would notice. + /// + /// `SKILL` alone, deliberately. It is the document that owns the CLI surface, and + /// the others teach one job with the handful of commands that job uses. Requiring + /// every subcommand of each of them would fill a review document with campaigns + /// and `init` to satisfy a test. #[test] fn every_agent_facing_subcommand_is_documented() { use clap::CommandFactory; @@ -279,4 +362,27 @@ mod tests { ); } } + + /// 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 + /// reviewer that ticks criteria or moves the ticket still runs, and produces a + /// board where nothing records that anyone disagreed. + #[test] + fn the_review_skill_keeps_the_decisions_that_define_it() { + for required in [ + "worklane show", // the ticket is read before the code + "nothing names the ticket", // and the no-work-found case is answered + "Never tick a criterion", + "Do not move the ticket", + "worklane uncheck", + "worklane append", + "cannot tell", + ] { + assert!( + REVIEW_SKILL.content.contains(required), + "the review skill no longer says {required:?}" + ); + } + } } diff --git a/src/main.rs b/src/main.rs index 73e7d1c..685bce5 100644 --- a/src/main.rs +++ b/src/main.rs @@ -87,7 +87,9 @@ fn main() -> Result<()> { Some(Command::Assign { campaign, ticket }) => cmd_assign(&campaign, &ticket, &start), // No board is looked for: the point of the skill is to teach an agent worklane // before there is a `.worklane` anywhere. - Some(Command::InstallSkill { force, print }) => cmd_install_skill(force, print), + Some(Command::InstallSkill { skill, force, print }) => { + cmd_install_skill(skill.as_deref(), force, print) + } } } diff --git a/tests/cmd_install_skill.rs b/tests/cmd_install_skill.rs index 7277312..467d881 100644 --- a/tests/cmd_install_skill.rs +++ b/tests/cmd_install_skill.rs @@ -3,9 +3,10 @@ use assert_fs::TempDir; const BIN_NAME: &str = env!("CARGO_BIN_EXE_worklane"); -/// The document as this test's binary carries it, so the print path is pinned to the -/// file in the repo rather than to a description of it. +/// The documents as this test's binary carries them, so the print path is pinned to the +/// 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"); /// `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 @@ -20,9 +21,17 @@ fn installed(home: &TempDir) -> std::path::PathBuf { home.path().join(".claude/skills/worklane/SKILL.md") } -/// Nothing about the skill needs a board, and it is wanted before there is one. +fn installed_review(home: &TempDir) -> std::path::PathBuf { + home.path().join(".claude/skills/worklane-review/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 +/// review skill existed gets it without learning anything new, which is the whole +/// reason there is no name to pass. #[test] -fn the_skill_installs_outside_a_worklane_directory() { +fn every_skill_installs_outside_a_worklane_directory() { let home = TempDir::new().unwrap(); let out = run(&home, &["install-skill"]); @@ -31,7 +40,46 @@ fn the_skill_installs_outside_a_worklane_directory() { assert_eq!(out.status.code(), Some(0), "{stdout}"); assert!(stdout.contains("Installed the worklane skill"), "{stdout}"); 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_eq!(std::fs::read_to_string(installed(&home)).unwrap(), SKILL); + assert_eq!(std::fs::read_to_string(installed_review(&home)).unwrap(), REVIEW); + + // Once, not per document: it is the one thing to do next, not part of an outcome. + assert_eq!( + stdout.matches("pick it up on their next session").count(), + 1, + "{stdout}" + ); +} + +/// Narrowing to one document is the exception, and it must leave the others alone. +#[test] +fn a_named_skill_installs_only_that_one() { + let home = TempDir::new().unwrap(); + + let out = run(&home, &["install-skill", "worklane-review"]); + let stdout = String::from_utf8_lossy(&out.stdout); + + 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"); +} + +/// A name nothing ships is a stop, with the choices in the message: guessing at the +/// nearest match would install a document nobody asked for. +#[test] +fn an_unknown_skill_name_is_refused_and_lists_what_there_is() { + let home = TempDir::new().unwrap(); + + let out = run(&home, &["install-skill", "reviewer"]); + let stderr = String::from_utf8_lossy(&out.stderr); + + assert_ne!(out.status.code(), Some(0), "{stderr}"); + assert!(stderr.contains("no skill named"), "{stderr}"); + assert!(stderr.contains("worklane-review"), "{stderr}"); + assert!(!installed(&home).exists()); + assert!(!installed_review(&home).exists()); } #[test] @@ -73,17 +121,56 @@ fn a_modified_copy_is_reported_and_needs_force() { assert_eq!(std::fs::read_to_string(installed(&home)).unwrap(), SKILL); } +/// One refused document must not stop the ones behind it: the message is per document, +/// and the run still reports what it did with each. +#[test] +fn a_modified_copy_does_not_stop_the_other_documents() { + let home = TempDir::new().unwrap(); + run(&home, &["install-skill"]); + std::fs::write(installed(&home), "hand written\n").unwrap(); + std::fs::remove_file(installed_review(&home)).unwrap(); + + let out = run(&home, &["install-skill"]); + let stdout = String::from_utf8_lossy(&out.stdout); + + assert_eq!(out.status.code(), Some(0), "{stdout}"); + assert!(stdout.contains("Differs from the version in this binary"), "{stdout}"); + 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); +} + /// The print path is what makes a modified copy diffable, so it has to be the document /// byte for byte and it must not install anything on the way past. #[test] -fn print_writes_the_document_to_stdout_and_installs_nothing() { +fn print_writes_the_named_document_to_stdout_and_installs_nothing() { + let home = TempDir::new().unwrap(); + + let out = run(&home, &["install-skill", "worklane", "--print"]); + assert_eq!(out.status.code(), Some(0)); + assert_eq!(String::from_utf8_lossy(&out.stdout), SKILL); + + let out = run(&home, &["install-skill", "worklane-review", "--print"]); + assert_eq!(out.status.code(), Some(0)); + assert_eq!(String::from_utf8_lossy(&out.stdout), REVIEW); + + assert!(!installed(&home).exists(), "--print installed the skill anyway"); + assert!(!installed_review(&home).exists(), "--print installed the skill anyway"); +} + +/// A diff is against one document. Printing them all run together would be neither of +/// them, so an unnamed `--print` says what to type instead of guessing. +#[test] +fn print_without_a_name_says_which_names_there_are() { let home = TempDir::new().unwrap(); let out = run(&home, &["install-skill", "--print"]); + let stderr = String::from_utf8_lossy(&out.stderr); - assert_eq!(out.status.code(), Some(0)); - assert_eq!(String::from_utf8_lossy(&out.stdout), SKILL); - assert!(!installed(&home).exists(), "--print installed the skill anyway"); + assert_ne!(out.status.code(), Some(0), "{stderr}"); + assert!(stderr.contains("name the skill to print"), "{stderr}"); + assert!(stderr.contains("worklane-review"), "{stderr}"); + assert!(String::from_utf8_lossy(&out.stdout).is_empty(), "a document was printed anyway"); } /// The command has to be findable by someone who does not already know it exists.