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.
12 KiB
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!fromassets/SKILL.md, not copied by an install script.cargo installplaces binaries and nothing else, so an installed document that is not in the binary is a document that drifts from it assets/SKILL.mdis 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 skillworklane_kanban, its examples still used short flags the CLI had stopped accepting, and it knew nothing aboutrelate,campaign,chown,checkor the four-status flow. It was not inert while it existed:opencode debug skilllisted 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 andinstall-skillis 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-incustomize-opencodeskill documents the table and whoseopencode debug skilllists what it found there. Do not add the second path: it is two copies of one document, free to drift, for no gain Assetcarries the content, the path under its root and the word used in messages, soinstall-tooladds an entry and its own root rather than a second copy of the compare-and-refuse logic. That is why the module isinstall.rsand notskill.rsinstall()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 redirectsHOMEfor the same reason- A modified copy is refused, not overwritten. Someone may have edited it on purpose, and the message names
--printso it can be diffed and--forceso 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 outsideNOT_FOR_AGENTShas to appear in the skill. The last one catches a new command that nothing tells an agent about install-skilllooks for no board. The skill is what teaches an agent worklane, so needing a.worklaneto 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.mdthere is the prior art the review skill grew out of and is deliberately left in place: its content is now inassets/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 nowassets/TOOL.tsand shipped like every other asset install-skillwrites 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--printrequires 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 thecomment --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 theworklaneskill 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 (mvbelongs 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 inreviewingis itself the finding) - The plan skill is the one that can do damage, so its rules are the ones under test.
set --tagsreplaces 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_sweeppins propose-then-apply and those two traps, because a document that loses them still reads like a plan .opencode/agent/feature-planner-agent.mdis deliberately not folded intoPLAN.md. It decomposes a feature request into new tickets, which is intake;PLAN.mdorders 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 documentinstall-toolis a second command, not a flag oninstall-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 addwith astdio,sseorhttptransport is the only way a tool enters its tool list, and its plugin system adoptsagents,hooks,monitors,workflows,output-stylesandthemesand nothing named tools. So an MCP server, a different artifact, would be what reached it. Verified against Claude Code 2.1.238tools_root()followsXDG_CONFIG_HOME,skills_root()does not.~/.claudeis not an XDG path and opencode's config root is:opencode debug pathsreports$XDG_CONFIG_HOME/opencodewith the variable set and~/.config/opencodewithout. An empty value counts as unset, the conventioncolors_wantedfollows forNO_COLOR.opencode_tool_dirtakes both variables as arguments for the reasoncolors_wanteddoes, 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/idsregistered 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 writesagent(s)andskill(s).opencode serveplus that endpoint is how to check this again; there is noopencode debug toolto ask worklane.tsis the file name the tool ids are built from. opencode names each tool as the file then the export, so the file's twenty-oneexport constlines becomeworklane_addthroughworklane_tags_set. Renaming the file renames every tool and every permission rule that mentions one, which is whyTOOL.relativeis 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/pluginimport resolves there: a copy in a project with nonode_modulesanywhere above it registered all of its tools, on a machine with nobunonPATH. 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,assignandtagshad 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_subcommandcatches 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_toolcatches 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 bareworklane campaignis refused by the CLI, its subcommand required, so there is no command for acampaigntool to wrap and the fivecampaign_*tools are the command - Installing it globally reproduces fb3dec6 for the wrapper. Global tools apply in every project including this one, so once
install-toolhas run, an agent working on worklane uses the installed copy ofassets/TOOL.tsand not the tree it is editing. Same trap as theworklaneonPATH, second instance every_agent_facing_subcommand_is_documentedstays onSKILLalone. 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 withinitand 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_tableincommand.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:campaignandassignshipped in 0.12.0 and were still absent from the table at 0.20.0, e6e3a1b, along with the--campaignflag on thelsrow. It walks clap's own subcommands, one level of nesting included, against the|lines ofREADME.md, so a new command fails the suite until the table lists it.helpis excluded, being clap's. The tag subcommands are named in aPENDINGlist rather than skipped, since f7dd1a1 rewrites that row and emptying the list is part of closing it