Files
worklane/docs/agent-assets.md
T
Ansho Rei 19c666b5dc Close a review of landed work by filing its remaining issues as tickets, and bump to 0.33.10
Work already on the default branch cannot go back to committed without
reopening shipped code. The reviewer files each remaining issue as a new
ticket, related issues together, comments why the ticket is closing, and
moves it to done.
2026-11-06 18:43:07 +01:00

12 KiB

Shipping the Agent Assets

The documents and the opencode tool file the binary carries, and how they are installed.

  • 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 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
  • 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) unless the work is already on master (then each finding gets its own ticket, related ones sharing one, and the reviewer moves the original to done once all of them are filed, after a comment saying which ticket holds each remaining issue, since a done ticket with unticked criteria otherwise reads as closed by mistake: sending landed work back to committed reopens shipped code, and leaving it in reviewing with nothing left to do only hides that the review is over), 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 every worklane tool the file carried, eleven at the time and twenty-one at the recheck after the wrapper caught up with the CLI. 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 twenty-one export const lines become worklane_add through worklane_tags_set. 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 of its 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 walks clap in both directions now; until this ticket nothing did. It was behind by four commands — relate, campaign, assign and tags had no tool, so an agent holding the tools could not reach campaigns or relations at all — and nothing compared the file to the CLI, which is how the gap opened and stayed open. every_tool_the_wrapper_exports_is_a_real_subcommand catches a tool for a command that has been renamed or dropped, which fails only when an agent finally calls it; every_subcommand_outside_the_exceptions_has_a_tool catches the other direction, a subcommand with no tool, through the same walk off clap the completion lists take. Its exception list carries a reason per entry rather than being bare, and one of those reasons was learned from the test's first run: a bare worklane campaign is refused by the CLI, its subcommand required, so there is no command for a campaign tool to wrap and the five campaign_* tools are the command
  • 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
  • The README command table has the same guard, every_subcommand_has_a_row_in_the_readme_command_table in command.rs. The skill and the table are the two places a command is discovered, one by an agent and one by a person, and the skill was the only one under test: campaign and assign shipped in 0.12.0 and were still absent from the table at 0.20.0, e6e3a1b, along with the --campaign flag on the ls row. It walks clap's own subcommands, one level of nesting included, against the | lines of README.md, so a new command fails the suite until the table lists it. help is excluded, being clap's. The tag subcommands are named in a PENDING list rather than skipped, since f7dd1a1 rewrites that row and emptying the list is part of closing it