(16c2bed) Add a worklane-review skill, and bump to 0.13.0
install-skill now writes every document the binary carries, with an optional name to narrow it. Requiring a name per document would mean a skill added later never reaches anyone who already knows the invocation, which is the drift the command exists to prevent. --print is the exception and requires the name: a diff is against one document. The review skill is its own document rather than a section of SKILL.md, because the frontmatter description is the whole of what decides loading and one description cannot name both "anything touching a ticket" and "only when a review is asked for". The reviewer never ticks a criterion and never moves the ticket. A tick is the implementer's claim and unticking is the review disagreeing; one mark for both loses the disagreement. mv belongs to whoever does the work. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5
parent
2c0a99f7c4
commit
d5fb22cfd8
+8
-1
@@ -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<String>,
|
||||
|
||||
/// Overwrite an existing copy that has been modified
|
||||
#[arg(long)]
|
||||
force: bool,
|
||||
|
||||
+46
-18
@@ -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(())
|
||||
}
|
||||
|
||||
|
||||
+143
-37
@@ -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::<Vec<_>>()
|
||||
.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/<name>/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:?}"
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
+3
-1
@@ -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)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user