From 6c43e62a4b762a667517f99b4fdc0f5479adc9d5 Mon Sep 17 00:00:00 2001 From: Ansho Rei Date: Fri, 21 Aug 2026 01:18:36 +0200 Subject: [PATCH] (8cc254c, 47aa0fe, a1dbd60) Fix the documented examples and the add tool schema Three doc tickets in one commit, since two of them are the same check: run everything the docs claim and see what fails. 8cc254c: the add example in the kanban skill passed -t twice, once where -g for tags was meant, and gave -p three bare positional values instead of three flags. Clap rejected it with exit 2, reproduced verbatim. Rewritten, with a line saying why -t is not tags and why each step needs its own -p, since the example alone does not explain the trap. The "--due (or --due)" filler is gone; --due and --priority have no short form and now say so. a1dbd60: only title is required in the add schema now. The other six fields were unmarked, so the model had to invent a value for every field on every ticket. The other four tool schemas were checked and are already right: ls is fully optional, and the required arguments on show, mv and comment are genuinely required. Every add field was already guarded in execute, so an omitted field adds no flag. 47aa0fe: the README row it describes was already fixed in passing by ddbd45e, which rewrote it for the priority work. "ls --status" appears nowhere. What was left was the second criterion, and running every example turned up a different problem: the 141 exit code documented for a truncated pipe only happens when the output exceeds the 64 KiB a pipe holds. A short listing lands in the buffer whole and reports 0. That was my own wording from b28ddb9 and it is now precise. Every example in both files was run against the built binary, with real ids substituted where they use placeholders, and the four documented exit codes were measured rather than assumed. Co-Authored-By: Claude Opus 5 (1M context) --- .../skill/worklane-kanban-skill/SKILL.md | 9 +++++--- .opencode/tools/worklane.ts | 21 +++++++++++++------ README.md | 5 +++++ 3 files changed, 26 insertions(+), 9 deletions(-) diff --git a/.opencode/skill/worklane-kanban-skill/SKILL.md b/.opencode/skill/worklane-kanban-skill/SKILL.md index 4db3e58..c1dbf76 100644 --- a/.opencode/skill/worklane-kanban-skill/SKILL.md +++ b/.opencode/skill/worklane-kanban-skill/SKILL.md @@ -35,12 +35,15 @@ Add a new ticket to the backlog. - `--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` (or `--due`): Due date in YYYY-MM-DD format +- `--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 +- `--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" -t login,auth -p "Design UI" "Build backend" "Write tests" --due 2026-06-01 --owner "ilya" +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. diff --git a/.opencode/tools/worklane.ts b/.opencode/tools/worklane.ts index 7b19404..b17be1b 100644 --- a/.opencode/tools/worklane.ts +++ b/.opencode/tools/worklane.ts @@ -87,28 +87,37 @@ export const init = tool({ export const add = tool({ description: "Add a new ticket to the worklane backlog. Requires a title. Description, acceptance criteria, and plan each support multiple lines (one item per line). Tags are comma-separated.", + // Title is the only required field. Every other flag is left off entirely when + // the field is omitted, so an unmarked schema only forced the model to invent a + // value for fields it had nothing to say about. args: { title: tool.schema .string() .describe("Ticket title (required)"), description: tool.schema .string() - .describe("Description text. Use newlines between paragraphs."), + .describe("Description text. Use newlines between paragraphs.") + .optional(), acceptance: tool.schema .string() - .describe("Acceptance criteria, one per line. Put each criterium on its own line."), + .describe("Acceptance criteria, one per line. Put each criterium on its own line.") + .optional(), plan: tool.schema .string() - .describe("Implementation plan steps, one per line. Put each step on its own line."), + .describe("Implementation plan steps, one per line. Put each step on its own line.") + .optional(), tags: tool.schema .string() - .describe("Comma-separated tags, e.g. 'bug,frontend,urgent'"), + .describe("Comma-separated tags, e.g. 'bug,frontend,urgent'") + .optional(), due: tool.schema .string() - .describe("Due date in YYYY-MM-DD format"), + .describe("Due date in YYYY-MM-DD format") + .optional(), owner: tool.schema .string() - .describe("Ticket owner name. If omitted, defaults to the git user."), + .describe("Ticket owner name. If omitted, defaults to the git user.") + .optional(), priority: tool.schema .string() .describe("Priority level, 1 (most urgent) to 5 (least). Left unset if omitted.") diff --git a/README.md b/README.md index bb37e4a..f3e2fc1 100644 --- a/README.md +++ b/README.md @@ -24,3 +24,8 @@ Worklane is a local Kanban flow for agentic software development. the default signal disposition so a truncated pipe is quiet, the way `head` and `sort` are, rather than printing a panic. A script using `set -o pipefail` will see 141 for a case that is not a failure, so guard for it there. + +Whether a truncated pipe reports 141 or 0 depends on the size of the output, not on +the command. A pipe holds 64 KiB, so a listing that fits lands in the buffer whole +and the writer never learns the reader left, giving 0. Only output past that gets far +enough to be cut off. Either way nothing is printed to stderr.