Compare commits

..
3 Commits
Author SHA1 Message Date
Ansho ReiandClaude Opus 5 50e67483d8 (b2c5531) Delete the stale copy of the worklane skill, and bump to 0.24.0
`.opencode/skill/worklane-kanban-skill/SKILL.md` was 223 lines of the same
document `assets/SKILL.md` holds, shipped by nothing and checked by no test.
It drifted the way a copy nobody reads does: its frontmatter still called the
skill `worklane_kanban`, its examples still used short flags, and it knew
nothing about `relate`, `campaign`, `chown`, `check` or the four-status flow.

It was not inert while it existed, and that was worth confirming rather than
assuming. `opencode debug skill` listed it by path, so an agent working in
this repo saw two worklane skills and could load either: the current one out
of `~/.claude/skills` or this one. After the delete the same command lists
`worklane`, `worklane-review` and `worklane-plan` and nothing else of ours.

The two agent files named it in their skill permission blocks,
`"worklane_kanban": "allow"`, an id only the deleted file defined, so the
permission granted access to nothing. Repointed at `worklane`, which is the
surviving document and what the grant meant. The files themselves stay: they
are the user's, and `reviewing-agent.md` is the prior art `assets/REVIEW.md`
grew out of. Neither was given `worklane-review` or `worklane-plan`, which
would be redesigning somebody else's agent rather than fixing a dead id.

`.opencode/skill/testing-skill` is untouched for the same reason. It is not a
copy of anything this repo ships.

8cc254c fixed the add example in the file this deletes, and it is moot rather
than reopened, recorded in a comment there. The fix was real: the example did
pass `-t` where `-g` was meant, gave `-p` three bare positionals, and clap
did reject it with exit 2. Nothing carries over, because `assets/SKILL.md`
never had either defect. Its examples are long flags throughout, one value
per flag, and it carries no "(or --due)" filler. Checked against the file.

AGENTS.md now says the surviving document is the only one and names this copy
as what happened last time, since the rule on its own does not say why it is
there.

The bump is the body of work's, not this commit's: `install-tool` in 11145b2
is the new command, and one bump on the last commit is what this tree does
when work spans several.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 14:26:57 +02:00
Ansho ReiandClaude Opus 5 11145b228e (c092ea7) Ship the opencode tool definitions with the binary, behind install-tool
`.opencode/tools/worklane.ts` was the second agent asset and the only one
that existed nowhere but a checkout. `cargo install` places binaries and
nothing else, so anyone who installed worklane got the skills and never the
tools, and the copy that did exist was reachable only from this repo. It is
now `assets/TOOL.ts`, embedded with `include_str!` like every other asset,
and `install-tool` writes it where opencode looks.

Its own command rather than a flag on `install-skill`, because the two
artifacts are not alike. A skill is inert markdown and one path serves both
agents. The tool is executable TypeScript and serves one: Claude Code has no
directory it scans for a tool definition, `claude mcp add` is the only way a
tool enters its list, and its plugin system adopts agents, hooks, monitors,
workflows, output-styles and themes and nothing named tools. Reaching it
would mean an MCP server, which is a different artifact and not this file.
So somebody on Claude Code takes the documents and never the wrapper, which
is the choice this command exists to give them.

The path was measured rather than guessed, as the ticket asked. 1.15.10
loads `~/.config/opencode/tool/` and `~/.config/opencode/tools/` both: each
was served in turn from a directory outside any project and
`/experimental/tool/ids` came back with all eleven worklane tools. Singular
is the target, the spelling opencode's own documentation puts first the way
it writes `agent(s)` and `skill(s)`. `tools_root()` follows
`XDG_CONFIG_HOME` where `skills_root()` does not, because opencode's config
root is an XDG path and `~/.claude` is not; `opencode debug paths` reports
`$XDG_CONFIG_HOME/opencode` with it set. An empty value counts as unset, the
convention `colors_wanted` already follows.

`opencode_tool_dir` takes both variables as arguments for the reason
`colors_wanted` does: a threaded test binary cannot mutate the process
environment to reach one branch at a time.

The file name is load bearing and now pinned by a test. opencode builds each
tool id as the file name then the export, so `worklane.ts` plus eleven
`export const` lines is what makes them `worklane_add` through
`worklane_uncheck`. Renaming the file renames every tool and every
permission rule naming one.

The closing line is not the skills' "on their next session". opencode reads
its config once at startup and never reloads it, so a running one keeps the
tools it began with and the honest instruction is to restart it.

Nothing else has to be installed, which is worth saying because the file is
executable and reads as though it wants a toolchain. Criterion 6 asked the
command to name the plugin package and Bun as runtime requirements and both
are wrong: a copy in a project with no `node_modules` above it registered
all eleven tools on a machine with no `bun` on `PATH`. opencode is a Bun
binary and the import resolves inside it. The message says the opposite, and
the reasoning is on the ticket.

`install_each` is the outcome loop both commands now share, with the
compare-and-refuse invocation passed in: that line is the only part of an
outcome that has to name the command it came from. What each command says
after the loop stays with the command.

`every_tool_the_wrapper_exports_is_a_real_subcommand` guards the direction
that breaks at call time, a tool wrapping a command that has been renamed or
dropped. Deliberately not the reverse: the wrapper has no tool for `relate`,
`campaign`, `assign` or `tags`, so an agent holding the tools cannot reach
campaigns or relations at all, and a test asserting that gap would fail on a
decision nobody has taken rather than on a mistake. Its own ticket.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 14:14:14 +02:00
Ansho ReiandClaude Opus 5 2ddd0addf6 (59b23b7) Stop the board walk on a link that does not resolve, and bump to 0.23.1
`find_worklane_dir` asked `exists()`, which follows a symlink. A `.worklane`
that was a dangling link therefore answered exactly as no `.worklane` at
all: the walk carried on up the tree, the first board above the project
became the board, and every write landed in it. Silently, and in the board
belonging to someone else's project.

Latent while a board is a real directory inside the project it belongs to.
Once boards live in one shared directory and `.worklane` is a link into it,
a dangling link stops being a corrupted tree and becomes an ordinary state:
it is what you have before the boards repo is cloned, and after a board
directory is renamed. So this is reachable on an ordinary day rather than
only with a hand-made link.

`classify` reads `symlink_metadata` first, so the answer is about the entry
rather than about its target, and it is one of four: `Absent`, `Board`,
`Dangling` or `NotADirectory`. `Absent` is the only one the walk carries on
from. A `.worklane` that is there but unusable is this project's board and
is reported here, not handed to whatever sits above it. Anything other than
`NotFound` out of `symlink_metadata` is an error too, since reading a
filesystem that could not answer as nothing-there is how the walk-past
worked in the first place.

The failure names the target and says the boards repo may not be cloned.
The old message, no board found and run `worklane init`, was wrong twice
over even with no board above: it describes an empty tree, and it points at
creating a board when the cause is an unsynced machine, which is the one
action that produces two boards with one name.

A regular file at that path is an error as well. It is a plausible future
pointer form and reading it as one is that change's decision to make;
stepping over it and writing above is the answer that is wrong today.

A link that resolves is still indistinguishable from a real directory, and
what comes back is the link rather than its target, so
`.worklane/backlog/*.md` reads the same either way and nothing downstream
learns whether the board is local.

Every writing command resolves the board before it writes, so the refusal
costs nothing halfway. `add` is where that is pinned end to end, against an
empty board above the project that stays empty. `init` is untouched: it
does not go through this walk, it writes nothing on a dangling link today,
and its symlink cases belong to the layout change.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 13:47:31 +02:00
15 changed files with 607 additions and 242 deletions
+1 -1
View File
@@ -17,7 +17,7 @@ permissions:
bash:
"sudo *": "deny"
skill:
"worklane_kanban": "allow"
"worklane": "allow"
---
# Feature Planner Agent
+1 -1
View File
@@ -17,7 +17,7 @@ permissions:
bash:
"sudo *": "deny"
skill:
"worklane_kanban": "allow"
"worklane": "allow"
"testing-skill": "allow"
---
@@ -1,223 +0,0 @@
---
id: worklane_kanban
name: worklane_kanban
version: 1.0.0
description: >
Creates Kanban-style tickets in Worklane using the `worklane add` CLI command.
Supports listing tickets with `worklane ls`. Both commands support title, description,
acceptance criteria, implementation plan, tags, due date, owner assignment, and status filtering.
rendering:
strategy: cli_args
join_arrays_with: ","
omit_empty: true
---
# Worklane Kanban Skill
Use this skill when creating, listing, or managing Kanban-style tickets via the `worklane` CLI.
When asked to "create a ticket", use the `worklane add` command.
When using backticks in the command arguments, escape them so the terminal doesn't execute them.
When asked to "implement", "work on" or "read" a ticket, use the `worklane show` command.
## Commands
### `worklane add`
Add a new ticket to the backlog.
**Required:**
- `--title` (or `-t`): Ticket title
**Optional:**
- `--description` (or `-d`): Ticket description
- `--acceptance` (or `-a`): Acceptance criteria (repeat flag for each criterium)
- `--plan` (or `-p`): Implementation plan steps (repeat flag for each step)
- `--tags` (or `-g`): Tags (comma-separated)
- `--due`: Due date in YYYY-MM-DD format. No short form
- `--owner` (or `-o`): Owner name
- `--priority`: Priority level, 1 (most urgent) to 5 (least). Unset if omitted. No short form
Tags are `-g`, not `-t`: `-t` is the title, and passing it twice is an error. Each
plan step needs its own `-p`, since a bare value after one is not a second step.
```bash
worklane add -t "Implement login" -d "Add user login page" -g login,auth -p "Design UI" -p "Build backend" -p "Write tests" --due 2026-06-01 --owner "ilya"
```
When there's multiple acceptance criteria, add each using a separate `--acceptance` or `-a` flag.
When there's mulitple steps to the implementation plan, add each using a separate `--plan` or `-p` flag.
```bash
worklane add -t "Implement logic" -a "Acceptance criterium 1" -a "Acceptance criterium 2" -p "Step 1" -p "Step 2"
```
### `worklane ls`
List tickets, optionally filtered by status.
**Valid statuses:** `backlog`, `committed`, `reviewing`, `done`
```
worklane ls # List all tickets
worklane ls backlog # List tickets in backlog
worklane ls done # List completed tickets
worklane ls --priority 1 # Only the most urgent, any status
worklane ls backlog --priority 2 # Composes with the status filter
```
Tickets are listed priority first, then by title. Tickets with no priority sort last.
### `worklane show`
Show the full details of a single ticket by UUID or title.
```
worklane show "ticket title or uuid"
```
### `worklane mv`
Move a ticket between statuses.
**Positional arguments:**
- `<id>`: Ticket UUID prefix (4+ characters) or title
**Required options:**
- `--status <target>`: Target status (`backlog`, `committed`, `reviewing`, `done`)
**Options:**
- `-f`: Force move (allows skipping stages and backward moves)
**Default behavior:** Only allows forward moves, one stage at a time (`backlog` -> `committed` -> `reviewing` -> `done`).
Examples:
```bash
worklane mv ticket-id --status committed # Move forward one stage
worklane mv ticket-title --status reviewing -f # Force skip stages
worklane mv a1b2c3d4 --status committed # Move by UUID prefix
worklane mv "My Ticket" --status done -f # Move by title with force
```
### `worklane set`
Replace fields on an existing ticket. Only the fields given are touched; ticked
criteria and handwritten sections are left alone. At least one field is required.
**Positional arguments:**
- `<ticket>`: Ticket UUID prefix (4+ characters) or title
**Options:** `--title`, `--description` (or `-d`), `--acceptance` (or `-a`), `--plan`
(or `-p`), `--tags` (or `-g`), `--due`, `--priority`
Owner is not settable here, and neither is status: `chown` owns owner and `mv` owns
status. Changing the title renames the file, keeping the UUID.
```bash
worklane set a1b2c3d4 --priority 1
worklane set a1b2c3d4 --title "A clearer title" --due 2026-12-31
worklane set a1b2c3d4 -a "First criterium" -a "Second criterium"
```
### `worklane append`
Add to a section without replacing what is there. The description gains a new
paragraph; criteria and steps go on the end of their lists, steps numbered on from
the last. At least one section is required.
**Positional arguments:**
- `<ticket>`: Ticket UUID prefix (4+ characters) or title
**Options:** `--description` (or `-d`), `--acceptance` (or `-a`), `--plan` (or `-p`)
```bash
worklane append a1b2c3d4 -d "A paragraph amending the description."
worklane append a1b2c3d4 -a "One more criterium"
worklane append a1b2c3d4 -p "A later step"
```
### `worklane chown`
Set the owner of a ticket. The only command that writes the Owner field: `set` does
not offer it.
**Positional arguments:**
- `<user>`: The new owner. Free text, checked against nothing
- `<ticket>`: Ticket UUID prefix (4+ characters) or title
The user comes first and the ticket second, after Unix `chown`. That is the one
command here that does not start with the ticket, so mind the order: swap the two and
the call fails, because the username has to resolve as a ticket. An owner set to the
value it already holds is reported unchanged and nothing is written.
```bash
worklane chown alice a1b2c3d4
worklane chown "Ansho Rei" "A clearer title"
```
### `worklane check` and `worklane uncheck`
Tick or untick a single acceptance criterion. Every other criterion keeps its state,
and handwritten lines in the section are left alone.
**Positional arguments:**
- `<ticket>`: Ticket UUID prefix (4+ characters) or title
- `[criterion]`: The number as shown by `worklane show`, or a substring of its text
Omit the criterion and the numbered criteria are listed and the number asked for. With
no terminal, as when driving the CLI from a tool, the same list comes back as an error
instead, so re-run with the number. A substring matching more than one criterion is an
error listing the matches with their real numbers.
```bash
worklane check a1b2c3d4 2
worklane check a1b2c3d4 "renames the file"
worklane uncheck a1b2c3d4 2
```
### `worklane comment`
Add a comment to a ticket.
**Positional arguments:**
- `<ticket>`: Ticket UUID prefix (4+ characters) or title
- `<body>`: Comment text
Comments are stored as timestamped markdown files in `.worklane/comments/<ticket-uuid>/` and include the git author and timestamp.
Examples:
```bash
worklane comment ticket-id "Reviewed, looks good"
worklane comment "My Ticket" "Needs changes to the UI"
worklane comment a1b2c3d4 "LGTM, approved"
```
## Working a ticket
Move the ticket as you work it, not afterwards. The board should say what is happening
now, not only what already landed.
1. `worklane show <id>` to read it
2. **`worklane mv <id> --status committed` before writing any code.** This is what marks
the ticket as being worked on, so it belongs at the start
3. Do the work. `worklane check <id> <n>` as each criterion is met
4. `worklane comment <id> <body>` with anything worth recording: a decision, a rejected
acceptance criterion, something the ticket got wrong
5. **`worklane mv <id> --status reviewing` once it is done and the tests pass**
Only one stage forward is allowed at a time, so a ticket left in `backlog` until the end
cannot go straight to `reviewing`. It has to be walked through `committed` anyway, which
makes moving it up front the same two commands in a more useful order.
## Commands
- `worklane add` creates tickets with all relevant details
- `worklane ls [status]` views tickets by status
- `worklane show <id>` views full ticket details
- `worklane mv <id> --status <target>` moves tickets through the workflow
- `worklane set <ticket>` corrects a field, `worklane append <ticket>` adds to a section
- `worklane check <ticket> <n>` ticks a criterion as it is met
- `worklane comment <ticket> <body>` adds notes to tickets
+18 -1
View File
@@ -13,6 +13,7 @@
- `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
- `assets/TOOL.ts` - the opencode tool definitions wrapping the CLI, embedded the same way and installed by `install-tool`. The only asset that is not a document and the only one that reaches a single agent
- `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/<status>/` directories
@@ -303,6 +304,13 @@ and this file is for what someone changing worklane's own code needs.
- `detail_body` closes a line only where the text says, so a part that does not end on a newline runs on into the next one. The seam between text and rows is wherever the body put it rather than wherever a part happened to end
- **The relations block is the only coloured part of the overlay body, and that is a decision, not an oversight.** The headings, the plan numbers, the criteria marks, the bold runs and the grey unset values are all painted by `show` and all flat on the board. The block earned its colour because it is where a reader compares several references at once, and because it was already data rather than prose: it arrives as rows for the status mark, so styling it cost nothing extra. Colouring the rest means giving every painted run in `content_parts` the `Cell` treatment, which is a much larger change with no reader's question behind it, and it is its own ticket. Do not paint one more section here without taking that on: two coloured sections and five plain ones reads as a bug, where one clearly does not
### Finding the Board
- **`find_worklane_dir` classifies the entry before it follows it.** `exists()` follows a link, so a `.worklane` that was a dangling symlink answered the same as no `.worklane` at all: the walk carried on up the tree and the first board above the project became the one every write landed in, silently. `classify` reads `symlink_metadata` first and answers one of four, `Absent`, `Board`, `Dangling` or `NotADirectory`, and **`Absent` is the only one the walk carries on from**. A `.worklane` that is there but unusable is this project's board and is reported, not handed upward
- Anything other than `NotFound` from `symlink_metadata` is an error rather than an `Absent`. Reading a filesystem that could not answer as nothing-there is how the walk-past worked in the first place
- The dangling failure **names the target and says the boards repo may not be cloned**, and deliberately does not say to run `worklane init`. Once the boards live outside the project a dangling link is an ordinary state, what you have before the boards repo is cloned and after a board directory is renamed, so "no board found, run init" points at the wrong problem
- **A link that resolves is indistinguishable from a real directory, and what comes back is the link rather than its target.** `.worklane/backlog/*.md` has to read the same either way and nothing downstream learns whether the board is local, which is the property the shared-boards layout rests on
- A regular file at that path is an error as well. It is a plausible future pointer form, and reading it as one is that change's decision to make; stepping over it and writing to a board above is the one answer that is wrong today
### Monitoring Several Boards
- `worklane tui <path>...` takes any number of paths, each resolved through `find_worklane_dir` the way the working directory is: the first `.worklane` at or above it. No path is the working directory, so a bare `worklane` and `worklane tui` are unchanged
- The failure **names the path** that had no board, since with several arguments "No .worklane directory found" does not say which one was wrong. Only when a path was given: a bare `worklane` has no path to name and keeps the message every other command gives, which is what its integration test asserts
@@ -319,13 +327,14 @@ and this file is for what someone changing worklane's own code needs.
### Shipping the Agent Assets
- The skill is embedded with `include_str!` from `assets/SKILL.md`, not copied by an install script. `cargo install` places binaries and nothing else, so an installed document that is not in the binary is a document that drifts from it
- **`assets/SKILL.md` is the only worklane skill document in this repo, and nothing may reintroduce a second.** There was one: `.opencode/skill/worklane-kanban-skill/SKILL.md`, 223 lines of the same document that nothing shipped and no test checked, and it drifted exactly as far as a copy nobody reads does. Its frontmatter still called the skill `worklane_kanban`, its examples still used short flags the CLI had stopped accepting, and it knew nothing about `relate`, `campaign`, `chown`, `check` or the four-status flow. It was **not** inert while it existed: `opencode debug skill` listed it, so an agent working in this repo saw two worklane skills and could load either. Deleted by b2c5531. A copy under `.opencode/`, in a second assets file, or in the README is the same mistake; the document has one home and `install-skill` is how it travels
- **One install path serves both agents:** `~/.claude/skills/worklane/SKILL.md`. Claude Code reads it, and opencode loads that directory as an external skill source alongside its own `~/.config/opencode/skill/`. Verified against opencode 1.15.10, whose built-in `customize-opencode` skill documents the table and whose `opencode debug skill` lists what it found there. Do not add the second path: it is two copies of one document, free to drift, for no gain
- `Asset` carries the content, the path under its root and the word used in messages, so `install-tool` adds an entry and its own root rather than a second copy of the compare-and-refuse logic. That is why the module is `install.rs` and not `skill.rs`
- `install()` takes the root as an argument. That is what lets the tests install into a temp directory instead of the home of whoever runs the suite, and the integration test redirects `HOME` for the same reason
- **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 <x>` 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. `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
- The **agent files** 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. The tool file is the exception and no longer lives there: it was `.opencode/tools/worklane.ts`, which meant it existed only inside a checkout, and it is now `assets/TOOL.ts` and shipped like every other asset
- **`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
@@ -334,6 +343,14 @@ and this file is for what someone changing worklane's own code needs.
- 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
- **`install-tool` is a second command, not a flag on `install-skill`, because the two artifacts are not alike.** A skill is inert markdown that any agent can read and it reaches both from one path; the tool is executable TypeScript that reaches opencode alone. Claude Code has no directory it scans for a tool definition at all: `claude mcp add` with a `stdio`, `sse` or `http` transport is the only way a tool enters its tool list, and its plugin system adopts `agents`, `hooks`, `monitors`, `workflows`, `output-styles` and `themes` and nothing named tools. So an MCP server, a different artifact, would be what reached it. Verified against Claude Code 2.1.238
- **`tools_root()` follows `XDG_CONFIG_HOME`, `skills_root()` does not.** `~/.claude` is not an XDG path and opencode's config root is: `opencode debug paths` reports `$XDG_CONFIG_HOME/opencode` with the variable set and `~/.config/opencode` without. An empty value counts as unset, the convention `colors_wanted` follows for `NO_COLOR`. `opencode_tool_dir` takes both variables as arguments for the reason `colors_wanted` does, since a threaded test binary cannot mutate the process environment to reach one branch at a time
- **Singular `tool`, and it was measured, not guessed.** opencode 1.15.10 loads `~/.config/opencode/tool/` and `~/.config/opencode/tools/` both: each was served in turn from a directory outside any project and `/experimental/tool/ids` registered all eleven worklane tools. The singular is the spelling opencode's own documentation puts first, the way it writes `agent(s)` and `skill(s)`. `opencode serve` plus that endpoint is how to check this again; there is no `opencode debug tool` to ask
- **`worklane.ts` is the file name the tool ids are built from.** opencode names each tool as the file then the export, so the file's eleven `export const` lines become `worklane_add` through `worklane_uncheck`. Renaming the file renames every tool and every permission rule that mentions one, which is why `TOOL.relative` is pinned by a test rather than left as a detail
- **The tool needs nothing installed beside opencode**, which is worth stating because the file is executable and reads as though it wants a toolchain. It is loaded into opencode's own Bun runtime and the `@opencode-ai/plugin` import resolves there: a copy in a project with no `node_modules` anywhere above it registered all eleven tools, on a machine with no `bun` on `PATH`. c092ea7's criterion 6 named those two as runtime requirements and it was wrong about both
- **The closing line differs from the skills', and that is not a wording choice.** opencode reads its config once at startup and never reloads it, so a running one keeps the tools it began with; the skills' "on their next session" would be a claim that is not true here
- **The wrapper is behind the CLI and nothing guards it.** It has no tool for `relate`, `campaign`, `assign` or `tags`, so an agent holding the tools cannot reach campaigns or relations at all. `every_tool_the_wrapper_exports_is_a_real_subcommand` catches the drift in the direction that breaks at call time, a tool for a command that no longer exists, and deliberately not the reverse: the gap is real, nobody has decided to close it, and a test asserting it would fail on that decision rather than on a mistake
- **Installing it globally reproduces fb3dec6 for the wrapper.** Global tools apply in every project including this one, so once `install-tool` has run, an agent working on worklane uses the installed copy of `assets/TOOL.ts` and not the tree it is editing. Same trap as the `worklane` on `PATH`, second instance
- `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
Generated
+1 -1
View File
@@ -1503,7 +1503,7 @@ dependencies = [
[[package]]
name = "worklane"
version = "0.23.0"
version = "0.24.0"
dependencies = [
"anyhow",
"assert_cmd",
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "worklane"
version = "0.23.0"
version = "0.24.0"
edition = "2024"
[dependencies]
+1
View File
@@ -26,6 +26,7 @@ Worklane is a local Kanban flow for agentic software development.
| `worklane tags` | Lists the tags the board carries as the tag, a tab and how many tickets carry it, one per line, unstyled and alphabetical. Case sensitive like `ls --tag`, so `bug` and `Bug` list separately and land next to each other. Every status, done included. The one command that answers what tags exist rather than what carries a tag already known |
| `worklane completions <shell>` | Prints a completion script for `fish`, `bash`, `zsh`, `elvish` or `powershell`. See below |
| `worklane install-skill [skill]` | Writes the embedded agent skills to `~/.claude/skills/<skill>/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 |
| `worklane install-tool` | Writes the embedded opencode tool definitions to `$XDG_CONFIG_HOME/opencode/tool/worklane.ts`, or `~/.config/opencode/tool/` without it, where opencode loads them for every project. One file and so no name to pass. `--force` and `--print` behave as they do for a skill. opencode only: it registers the eleven `worklane_*` tools from the file name and its exports, and Claude Code has no directory it scans for a tool definition, so reaching it would mean an MCP server rather than this. Restart opencode after installing, since it reads its config at startup and never reloads it. Nothing else to install: the file runs inside opencode's own runtime, so neither Bun nor `@opencode-ai/plugin` has to be on the machine |
## Completions
+17
View File
@@ -281,6 +281,23 @@ pub enum Command {
#[arg(long)]
print: bool,
},
/// Install the opencode tool definitions that wrap the worklane CLI
///
/// One artifact, so no name to pass where `install-skill` takes an optional one:
/// `--print` here can only mean the one file. opencode alone, and globally, so the
/// tools are there in every project rather than in a checkout that happens to carry
/// them. Claude Code has no directory it scans for a tool definition; reaching it
/// would mean an MCP server, which is not this file.
InstallTool {
/// Overwrite an existing copy that has been modified
#[arg(long)]
force: bool,
/// Write it to stdout instead of installing it
#[arg(long)]
print: bool,
},
}
/// What a campaign can be asked for.
+60 -8
View File
@@ -1562,9 +1562,38 @@ pub fn cmd_install_skill(skill: Option<&str>, force: bool, print: bool) -> Resul
};
let root = install::skills_root()?;
let written = install_each(&chosen, &root, force, |asset| {
format!("worklane install-skill {} --print", 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(())
}
/// Write each asset under `root` and report what happened to it.
///
/// Shared by both install commands, which differ in what they install and in what they
/// say afterwards, never in how an outcome is reported. `compare` is the invocation the
/// refusal points at, which is the one line that has to name the command it came from.
///
/// Returns whether anything was written, because that is what decides the closing line:
/// each command has its own thing to say about what picks the asset up, and neither
/// should say it once per asset.
fn install_each(
chosen: &[&install::Asset],
root: &Path,
force: bool,
compare: impl Fn(&install::Asset) -> String,
) -> Result<bool> {
let mut written = false;
for asset in chosen {
match asset.install(&root, force)? {
match asset.install(root, force)? {
install::Outcome::Written(path) => {
println!("Installed the {} {} to: {}", asset.name, asset.what, path.display());
written = true;
@@ -1574,18 +1603,41 @@ pub fn cmd_install_skill(skill: Option<&str>, force: bool, print: bool) -> Resul
}
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
);
println!("Compare with `{}`, or overwrite with --force", compare(asset));
}
}
}
// 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.
Ok(written)
}
/// Install the opencode tool definitions.
///
/// No name argument, where `install-skill` has an optional one: there is a single tool
/// file, so a name could only be right or wrong, and `--print` needs no help deciding
/// what to print.
pub fn cmd_install_tool(force: bool, print: bool) -> Result<()> {
if print {
print!("{}", install::TOOL.content);
return Ok(());
}
let chosen: Vec<&install::Asset> = install::TOOLS.iter().collect();
let root = install::tools_root()?;
let written =
install_each(&chosen, &root, force, |_| "worklane install-tool --print".to_string())?;
// Not "on its next session", which is what the skills say: opencode reads its config
// once at startup and does not reload it, so a running one keeps the tools it began
// with. The second line is there because the file is executable and looks like it
// needs a toolchain: it does not, it runs inside opencode.
if written {
println!("Claude Code and opencode pick it up on their next session");
println!(
"opencode loads it in every project. Restart it: the config is read at startup and never reloaded"
);
println!(
"Nothing else to install. It runs in opencode's own runtime, so neither Bun nor @opencode-ai/plugin is needed on this machine"
);
}
Ok(())
+151 -4
View File
@@ -11,9 +11,11 @@
//! 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.
//! The machinery is written once for both kinds of asset. The tool file is executable
//! code and reaches opencode alone, so it gets its own command and its own root, but the
//! compare-and-refuse logic is the same and lives here. What it needs at runtime is
//! opencode and nothing else: it is loaded into opencode's own runtime, so neither Bun
//! nor `@opencode-ai/plugin` has to be installed for the import in it to resolve.
use std::io;
use std::path::{Path, PathBuf};
@@ -73,6 +75,33 @@ pub const PLAN_SKILL: Asset = Asset {
/// statement that took it: a `const` is inlined at each use and the borrow dies there.
pub static SKILLS: [Asset; 3] = [SKILL, REVIEW_SKILL, PLAN_SKILL];
/// The opencode tool definitions, the second kind of asset this binary carries.
///
/// Executable TypeScript rather than a document, and it reaches one agent where a skill
/// reaches both: opencode loads a `.ts` file from its tool directory and Claude Code has
/// no directory it scans for one, so this is not the artifact that would reach it. That
/// asymmetry is the whole reason it is its own command with its own root rather than a
/// flag on `install-skill`.
///
/// Flat in the root rather than in a directory of its own, and the file name is load
/// bearing: opencode builds each tool id as the file name then the export, so this file
/// is what makes them `worklane_add` and `worklane_mv` rather than `tool_add`. A skill
/// carries the equivalent in its frontmatter `name:`, which its directory has to agree
/// with; a tool carries it in the file name alone.
pub const TOOL: Asset = Asset {
name: "worklane",
what: "tool",
relative: "worklane.ts",
content: include_str!("../assets/TOOL.ts"),
};
/// Every tool this binary carries.
///
/// One, and an array anyway: it is what keeps the install loop the same shape as the
/// skills', so a second tool needs no new machinery. A `static` for the reason `SKILLS`
/// is one.
pub static TOOLS: [Asset; 1] = [TOOL];
/// The skill a name on the command line asks for.
pub fn skill_named(name: &str) -> Result<&'static Asset> {
SKILLS
@@ -106,6 +135,48 @@ pub fn skills_root() -> Result<PathBuf> {
Ok(Path::new(&home).join(".claude/skills"))
}
/// Where the tool has to sit for opencode to load it in every project.
///
/// `XDG_CONFIG_HOME` when it is set and non-empty, `~/.config` otherwise, which is what
/// opencode itself resolves: `opencode debug paths` reports its config root under
/// `$XDG_CONFIG_HOME/opencode` with the variable set and `~/.config/opencode` without.
/// An empty value counts as unset, the convention `colors_wanted` already follows for
/// `NO_COLOR`. Checked against opencode 1.15.10.
///
/// Singular `tool`, though 1.15.10 loads `tools` as well: each was served in turn from a
/// directory outside any project and registered all eleven worklane tools. The singular
/// is the spelling opencode's own documentation puts first, the way it writes `agent(s)`
/// and `skill(s)`.
///
/// One agent, unlike `skills_root`. Claude Code has no path that belongs here at all: a
/// tool reaches it through an MCP server, which is a different artifact and not one this
/// binary carries.
pub fn tools_root() -> Result<PathBuf> {
let xdg = std::env::var_os("XDG_CONFIG_HOME");
let home = std::env::var_os("HOME");
opencode_tool_dir(xdg.as_deref().map(Path::new), home.as_deref().map(Path::new))
}
/// `tools_root` with the two variables passed in rather than read.
///
/// The seam exists for the reason `colors_wanted` has one: both branches and the failure
/// have to be reachable from a test, and a threaded test binary cannot mutate the process
/// environment to reach them one at a time.
fn opencode_tool_dir(xdg: Option<&Path>, home: Option<&Path>) -> Result<PathBuf> {
if let Some(xdg) = xdg.filter(|value| !value.as_os_str().is_empty()) {
return Ok(xdg.join("opencode/tool"));
}
let home = home.ok_or_else(|| {
anyhow!(
"cannot tell where your opencode config lives because neither XDG_CONFIG_HOME nor HOME is set in the environment"
)
})?;
Ok(home.join(".config/opencode/tool"))
}
#[derive(Debug, PartialEq, Eq)]
pub enum Outcome {
Written(PathBuf),
@@ -331,7 +402,7 @@ mod tests {
/// Subcommands the skill has no business teaching: the board is interactive and
/// belongs to a person, `install-skill` is how the document arrived, and `help`
/// is clap's own.
const NOT_FOR_AGENTS: [&str; 3] = ["tui", "install-skill", "help"];
const NOT_FOR_AGENTS: [&str; 4] = ["tui", "install-skill", "install-tool", "help"];
/// 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.
@@ -417,4 +488,80 @@ mod tests {
);
}
}
// ------------------------------------------------------------ the tool --
/// `XDG_CONFIG_HOME` wins, because it is what opencode itself resolves its config
/// root from: `opencode debug paths` reports `$XDG_CONFIG_HOME/opencode` with it set.
#[test]
fn the_tool_root_follows_xdg_config_home_when_it_is_set() {
let root = opencode_tool_dir(Some(Path::new("/tmp/xdg")), Some(Path::new("/home/x")));
assert_eq!(root.unwrap(), Path::new("/tmp/xdg/opencode/tool"));
}
/// An empty value counts as unset, the convention `colors_wanted` already follows, so
/// a wrapper script that cleared an inherited one still lands in the home directory
/// rather than at `/opencode/tool`.
#[test]
fn an_empty_xdg_config_home_falls_back_to_the_home_directory() {
let root = opencode_tool_dir(Some(Path::new("")), Some(Path::new("/home/x")));
assert_eq!(root.unwrap(), Path::new("/home/x/.config/opencode/tool"));
let unset = opencode_tool_dir(None, Some(Path::new("/home/x")));
assert_eq!(unset.unwrap(), Path::new("/home/x/.config/opencode/tool"));
}
/// Neither one set is the case that has to fail rather than guess: writing to a
/// relative `.config/opencode/tool` would put the tool wherever the caller happened
/// to be standing.
#[test]
fn neither_variable_set_is_an_error_rather_than_a_relative_path() {
let error = opencode_tool_dir(None, None).unwrap_err().to_string();
assert!(error.contains("XDG_CONFIG_HOME"), "{error}");
assert!(error.contains("HOME"), "{error}");
}
/// The file name is the tool id prefix, not decoration: opencode names each tool as
/// the file then the export, so a renamed file renames all eleven tools and every
/// permission rule that mentions one.
#[test]
fn the_tool_lands_flat_in_the_root_under_the_name_that_prefixes_its_ids() {
let root = opencode_tool_dir(None, Some(Path::new("/home/x"))).unwrap();
assert_eq!(TOOL.path(&root), Path::new("/home/x/.config/opencode/tool/worklane.ts"));
assert_eq!(TOOL.relative, "worklane.ts");
}
/// Every tool the file exports names a real subcommand.
///
/// The guard the fish completion lists already have, pointed the other way: this
/// catches a tool wrapping a command that has been renamed or dropped, which would
/// fail only when an agent finally called it. It cannot catch the reverse, a
/// subcommand the wrapper never grew a tool for, and the wrapper is behind by
/// several: `relate`, `campaign`, `assign` and `tags` have no tool. That is its own
/// ticket, and asserting it here would fail on a gap nobody has decided to close.
#[test]
fn every_tool_the_wrapper_exports_is_a_real_subcommand() {
use clap::CommandFactory;
let commands: Vec<String> = crate::Cli::command()
.get_subcommands()
.map(|command| command.get_name().to_string())
.collect();
let exported: Vec<&str> = TOOL
.content
.lines()
.filter_map(|line| line.strip_prefix("export const "))
.filter_map(|rest| rest.split_whitespace().next())
.collect();
assert_eq!(exported.len(), 11, "{exported:?}");
for name in exported {
assert!(
commands.iter().any(|command| command == name),
"the wrapper exports {name:?}, which is not a subcommand: {commands:?}"
);
}
}
}
+3
View File
@@ -92,6 +92,9 @@ fn main() -> Result<()> {
Some(Command::InstallSkill { skill, force, print }) => {
cmd_install_skill(skill.as_deref(), force, print)
}
// No board either, and one agent rather than both: opencode loads the tool file,
// Claude Code has no path for one.
Some(Command::InstallTool { force, print }) => cmd_install_tool(force, print),
}
}
+177 -2
View File
@@ -254,13 +254,87 @@ pub fn color_text(text: &str, color: Color) -> String {
paint(text, color, should_use_colors())
}
/// What sits at a candidate `.worklane` path.
///
/// The distinction the walk turns on is between nothing there and something
/// unusable there. `exists()` follows a link, so a dangling one answered the same
/// as an empty parent and the walk carried on upward until it met a board above
/// the project, which then became the board every write went to. Silently. With
/// the boards kept outside the project a dangling link is an ordinary state
/// rather than a corrupted tree: it is what you have before the boards repo is
/// cloned, and after a board directory is renamed.
#[derive(Debug, PartialEq)]
enum Candidate {
/// Nothing at that path, which is the one answer the walk carries on from.
Absent,
/// A directory, or a link that resolves to one.
Board,
/// A link that resolves to nothing, carrying the target it names.
Dangling(std::path::PathBuf),
/// There, and not a directory: a regular file, or a link to one.
NotADirectory,
}
/// Which of the four a `.worklane` path is.
///
/// `symlink_metadata` first, so the answer is about the entry itself and absence
/// cannot be confused with a target that is gone. Only then is the link followed,
/// which is what makes a resolvable one indistinguishable from a real directory.
fn classify(path: &Path) -> Result<Candidate> {
let entry = match fs::symlink_metadata(path) {
Ok(entry) => entry,
Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(Candidate::Absent),
// Anything other than absence is a filesystem that could not answer, and
// reading that as absence is how the walk-past worked in the first place.
Err(error) => return Err(anyhow!("Could not read {}: {error}", path.display())),
};
if !entry.is_symlink() {
return Ok(match entry.is_dir() {
true => Candidate::Board,
false => Candidate::NotADirectory,
});
}
// Read whether or not it resolves: the target is the only part of the failure
// that says what to go and fix.
let target = fs::read_link(path).unwrap_or_else(|_| path.to_path_buf());
Ok(match fs::metadata(path) {
Ok(resolved) if resolved.is_dir() => Candidate::Board,
Ok(_) => Candidate::NotADirectory,
Err(_) => Candidate::Dangling(target),
})
}
/// The first `.worklane` at or above `start`.
///
/// The symlink stays unresolved in what is returned, so a board reached through a
/// link is the same path to everything downstream as one sitting in the project.
pub fn find_worklane_dir(start: &Path) -> Result<std::path::PathBuf> {
let mut current = start.canonicalize()?;
loop {
let worklane_dir = current.join(".worklane");
if worklane_dir.exists() {
return Ok(worklane_dir);
match classify(&worklane_dir)? {
Candidate::Board => return Ok(worklane_dir),
// The only answer that hands the search upward. A `.worklane` that is
// there but unusable is this project's board and is reported here,
// rather than quietly becoming a write to whatever sits above it.
Candidate::Absent => {}
Candidate::Dangling(target) => {
return Err(anyhow!(
"{} is a symlink to {}, which does not exist. The boards repo may not be cloned on this machine.",
worklane_dir.display(),
target.display()
));
}
Candidate::NotADirectory => {
return Err(anyhow!(
"{} is not a directory. A board is a directory of ticket files.",
worklane_dir.display()
));
}
}
if !current.pop() {
@@ -4777,4 +4851,105 @@ mod tests {
"{rendered:?}"
);
}
// ----------------------------------------------------- finding the board --
/// A project directory under a temp root.
///
/// The root is canonicalized because `find_worklane_dir` canonicalizes its
/// start: on a system whose temp path runs through a link, the two spellings
/// of the same directory would not compare equal.
fn project_in(root: &tempfile::TempDir) -> std::path::PathBuf {
let dir = root.path().canonicalize().unwrap().join("project");
fs::create_dir_all(&dir).unwrap();
dir
}
/// The failure names the target, since the link is not the thing to fix, and it
/// does not say to run `init`: that answer belongs to an empty tree, and giving
/// it here points at the wrong problem.
#[test]
fn a_dangling_board_link_is_reported_with_its_target() {
let root = tempfile::tempdir().unwrap();
let project = project_in(&root);
let target = project.parent().unwrap().join("boards/2fed877-the-board");
std::os::unix::fs::symlink(&target, project.join(".worklane")).unwrap();
let error = find_worklane_dir(&project).unwrap_err().to_string();
assert!(error.contains(&target.display().to_string()), "{error}");
assert!(error.contains("boards repo"), "{error}");
assert!(!error.contains("worklane init"), "{error}");
}
/// The bug this was written for: `exists()` follows the link, so a dangling one
/// answered false, the walk carried on up the tree, and the board above the
/// project became the board every write landed in.
#[test]
fn a_dangling_board_link_does_not_reach_the_board_above_it() {
let root = tempfile::tempdir().unwrap();
let project = project_in(&root);
let above = project.parent().unwrap().join(".worklane");
fs::create_dir_all(&above).unwrap();
let link = project.join(".worklane");
std::os::unix::fs::symlink(project.parent().unwrap().join("gone"), &link).unwrap();
let error = find_worklane_dir(&project).unwrap_err().to_string();
assert!(error.contains(&link.display().to_string()), "{error}");
// And the walk really would have reached it, so the assertion above is
// about where the walk stopped rather than about an empty tree.
assert_eq!(find_worklane_dir(project.parent().unwrap()).unwrap(), above);
}
/// Nothing at that path is still the one answer the walk carries on from.
#[test]
fn no_worklane_at_all_lets_the_walk_carry_on_upward() {
let root = tempfile::tempdir().unwrap();
let project = project_in(&root);
let above = project.parent().unwrap().join(".worklane");
fs::create_dir_all(&above).unwrap();
assert_eq!(find_worklane_dir(&project).unwrap(), above);
}
/// A link that resolves is the board, and what comes back is the link rather
/// than its target: `.worklane/backlog` has to read the same either way.
#[test]
fn a_link_to_a_board_resolves_the_way_a_directory_does() {
let root = tempfile::tempdir().unwrap();
let project = project_in(&root);
let board = project.parent().unwrap().join("boards/2fed877-the-board");
fs::create_dir_all(&board).unwrap();
let link = project.join(".worklane");
std::os::unix::fs::symlink(&board, &link).unwrap();
assert_eq!(find_worklane_dir(&project).unwrap(), link);
}
/// A regular file is reported rather than stepped over, and a board above it
/// does not make it the walk's problem to solve.
#[test]
fn a_regular_file_where_the_board_goes_is_an_error() {
let root = tempfile::tempdir().unwrap();
let project = project_in(&root);
fs::write(project.join(".worklane"), "board = \"2fed877\"\n").unwrap();
fs::create_dir_all(project.parent().unwrap().join(".worklane")).unwrap();
let error = find_worklane_dir(&project).unwrap_err().to_string();
assert!(error.contains("not a directory"), "{error}");
}
/// A link that resolves to a file, which the follow catches and the entry check
/// on its own cannot: the entry is a symlink and the target is not a directory.
#[test]
fn a_link_to_a_file_is_not_a_board_either() {
let root = tempfile::tempdir().unwrap();
let project = project_in(&root);
let file = project.parent().unwrap().join("pointer.toml");
fs::write(&file, "board = \"2fed877\"\n").unwrap();
std::os::unix::fs::symlink(&file, project.join(".worklane")).unwrap();
let error = find_worklane_dir(&project).unwrap_err().to_string();
assert!(error.contains("not a directory"), "{error}");
}
}
+27
View File
@@ -597,3 +597,30 @@ fn add_names_the_ticket_and_the_path_when_the_write_fails() {
chmod(&backlog, 0o755);
assert_eq!(fs::read_dir(&backlog).unwrap().count(), 0);
}
/// The board above the project is real and empty, and stays empty: a dangling
/// `.worklane` link used to read as no board here, and the walk then wrote the
/// ticket into whatever board sat above it.
#[test]
fn add_writes_nothing_when_the_board_link_does_not_resolve() {
let temp = TempDir::new().unwrap();
let above = setup_worklane(&temp);
let project = temp.child("project");
project.create_dir_all().unwrap();
let target = temp.path().join("boards/2fed877-the-board");
std::os::unix::fs::symlink(&target, project.path().join(".worklane")).unwrap();
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
let assert = cmd
.current_dir(project.path())
.args(["add", "--title", "Should not land"])
.assert()
.failure();
let stderr = String::from_utf8(assert.get_output().stderr.clone()).unwrap();
assert!(stderr.contains(&target.display().to_string()), "{stderr}");
assert!(stderr.contains("boards repo"), "{stderr}");
assert_eq!(fs::read_dir(above.join("backlog")).unwrap().count(), 0);
}
+149
View File
@@ -0,0 +1,149 @@
use assert_cmd::Command;
use assert_fs::TempDir;
const BIN_NAME: &str = env!("CARGO_BIN_EXE_worklane");
/// The tool 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.
const TOOL: &str = include_str!("../assets/TOOL.ts");
/// `XDG_CONFIG_HOME` is redirected, and `HOME` with it, so the suite never writes into
/// the config of whoever runs it. Both, because the fallback reads `HOME` and a machine
/// that has neither set is not the case under test here.
fn run(config: &TempDir, args: &[&str]) -> std::process::Output {
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.env("XDG_CONFIG_HOME", config.path())
.env("HOME", config.path())
.args(args);
cmd.assert().get_output().clone()
}
fn installed(config: &TempDir) -> std::path::PathBuf {
config.path().join("opencode/tool/worklane.ts")
}
fn stdout(output: &std::process::Output) -> String {
String::from_utf8(output.stdout.clone()).unwrap()
}
/// Nothing about the tool needs a board, and it is wanted before there is one.
///
/// The file name is asserted, not just the directory: opencode names each tool as the
/// file then the export, so `worklane.ts` is what makes them `worklane_add` and
/// `worklane_mv`.
#[test]
fn the_tool_installs_outside_a_worklane_directory() {
let config = TempDir::new().unwrap();
let output = run(&config, &["install-tool"]);
assert!(output.status.success());
assert_eq!(std::fs::read_to_string(installed(&config)).unwrap(), TOOL);
assert!(
stdout(&output).contains("Installed the worklane tool"),
"{}",
stdout(&output)
);
}
/// What the message has to carry, and it is not the skills' "next session": opencode
/// reads its config once at startup and never reloads it, so a running one keeps the
/// tools it began with. The second half is there because the file is executable and
/// looks like it needs a toolchain, which it does not.
#[test]
fn the_tool_says_to_restart_opencode_and_that_nothing_else_is_needed() {
let config = TempDir::new().unwrap();
let out = stdout(&run(&config, &["install-tool"]));
assert!(out.contains("Restart it"), "{out}");
assert!(out.contains("never reloaded"), "{out}");
assert!(out.contains("Nothing else to install"), "{out}");
assert!(out.contains("Bun"), "{out}");
}
/// Installing twice is a no-op rather than a rewrite, exactly as `install-skill` is.
#[test]
fn a_second_install_reports_the_copy_unchanged() {
let config = TempDir::new().unwrap();
run(&config, &["install-tool"]);
let out = stdout(&run(&config, &["install-tool"]));
assert!(out.contains("Already up to date"), "{out}");
assert!(!out.contains("Installed the"), "{out}");
}
/// An edited copy is somebody's work, and the refusal names the invocation that shows
/// what it would be replaced with. `--print` there and not a skill name: there is one
/// tool file, so nothing has to say which.
#[test]
fn a_modified_copy_is_refused_until_force() {
let config = TempDir::new().unwrap();
run(&config, &["install-tool"]);
std::fs::write(installed(&config), "// hand written\n").unwrap();
let refused = stdout(&run(&config, &["install-tool"]));
assert!(refused.contains("Differs from the version in this binary"), "{refused}");
assert!(refused.contains("worklane install-tool --print"), "{refused}");
assert_eq!(std::fs::read_to_string(installed(&config)).unwrap(), "// hand written\n");
let forced = stdout(&run(&config, &["install-tool", "--force"]));
assert!(forced.contains("Installed the worklane tool"), "{forced}");
assert_eq!(std::fs::read_to_string(installed(&config)).unwrap(), TOOL);
}
/// `--print` is for diffing against an installed copy, so it writes nothing.
#[test]
fn print_writes_the_tool_to_stdout_and_installs_nothing() {
let config = TempDir::new().unwrap();
let output = run(&config, &["install-tool", "--print"]);
assert_eq!(stdout(&output), TOOL);
assert!(!installed(&config).exists());
}
/// With no `XDG_CONFIG_HOME` the tool lands under `HOME`, which is the same answer
/// opencode gives: its config root is `$XDG_CONFIG_HOME/opencode` when that is set and
/// `~/.config/opencode` when it is not.
#[test]
fn the_tool_falls_back_to_the_home_directory_without_xdg_config_home() {
let home = TempDir::new().unwrap();
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
let output = cmd
.env_remove("XDG_CONFIG_HOME")
.env("HOME", home.path())
.arg("install-tool")
.assert()
.success()
.get_output()
.clone();
let path = home.path().join(".config/opencode/tool/worklane.ts");
assert_eq!(std::fs::read_to_string(&path).unwrap(), TOOL);
assert!(
stdout(&output).contains(&path.display().to_string()),
"{}",
stdout(&output)
);
}
/// The two commands are independent, which is the whole point of them being two: a
/// person on Claude Code takes the skills and never the tool, and one who wants the
/// tools is not made to take a second copy of the documents to get them.
#[test]
fn each_install_command_leaves_the_other_target_alone() {
let config = TempDir::new().unwrap();
run(&config, &["install-tool"]);
assert!(installed(&config).exists());
assert!(!config.path().join(".claude/skills").exists());
let skills_only = TempDir::new().unwrap();
run(&skills_only, &["install-skill"]);
assert!(
skills_only
.path()
.join(".claude/skills/worklane/SKILL.md")
.exists()
);
assert!(!installed(&skills_only).exists());
}