@lanework/contracts 0.3.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -8,6 +8,10 @@ desktop app, its checkpoint hook, the Lanework API and their MCP servers.
8
8
  shapes in `outputs.ts` for parity checks), lanework-kit's search tools
9
9
  (`kit.ts`) and the conductor/lead control tools (`control.ts`), each with
10
10
  its input JSON Schema.
11
+ - **Agent rules** (`src/tools/instructions.ts`): `BOARD_INSTRUCTIONS` and
12
+ `BOARD_WORKER_INSTRUCTIONS`, the text both board MCP servers send on
13
+ `initialize`; `AGENT_NOTES`, the short pointer a project's AGENTS.md
14
+ carries instead of the rules.
11
15
 
12
16
  It has no runtime dependencies.
13
17
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lanework/contracts",
3
- "version": "0.3.0",
3
+ "version": "0.4.1",
4
4
  "type": "module",
5
5
  "description": "The contract between the Lanework desktop app, its checkpoint hook, the Lanework API and their MCP servers: HTTP request and response shapes, the board, kit and control tool contracts (types, JSON Schema builders and run-time output shapes).",
6
6
  "license": "MIT",
@@ -22,7 +22,8 @@
22
22
  },
23
23
  "//": "Types, JSON Schema builders and output shapes only, no runtime dependencies. The desktop app (open source) and the API and MCP (private) both build on it; neither half may be imported here.",
24
24
  "scripts": {
25
- "typecheck": "tsc --noEmit"
25
+ "typecheck": "tsc --noEmit",
26
+ "check:size": "bun scripts/check-size.ts"
26
27
  },
27
28
  "homepage": "https://github.com/lanework-dev/contracts#readme",
28
29
  "bugs": {
@@ -21,8 +21,30 @@ export const MCP_WORKER_URL = "https://mcp.lanework.dev/v1?toolset=worker";
21
21
  /** The MCP host alone, which any lanework config or note contains. */
22
22
  export const MCP_HOST = "mcp.lanework.dev";
23
23
 
24
+ /**
25
+ * The board section of a project's AGENTS.md: a pointer, not the rules.
26
+ *
27
+ * The rules ship with the tools, as the MCP server's `instructions`
28
+ * (`BOARD_INSTRUCTIONS`), so every harness gets them on connect and a server
29
+ * update updates them everywhere. This only names the server and what to do
30
+ * without it.
31
+ */
24
32
  export const AGENT_NOTES = `## Lanework board
25
33
 
34
+ Cards for this repo live on Lanework, through the \`lanework\` MCP server.
35
+ Follow its instructions for finding the board, writing cards and working
36
+ them. If the server is not connected, say so and stop rather than tracking
37
+ the work another way.`;
38
+
39
+ /**
40
+ * Board sections the app wrote before, verbatim, newest first. A project
41
+ * whose AGENTS.md still holds one of them is offered the current
42
+ * {@link AGENT_NOTES} in its place; anything a person reworded is theirs and
43
+ * is never replaced.
44
+ */
45
+ export const AGENT_NOTES_PREVIOUS: readonly string[] = [
46
+ `## Lanework board
47
+
26
48
  Cards for this repo live on Lanework, through the \`lanework\` MCP server.
27
49
 
28
50
  - Find the board with \`git remote get-url origin\`, then
@@ -43,4 +65,5 @@ Cards for this repo live on Lanework, through the \`lanework\` MCP server.
43
65
  by wave, one sub-agent per stream in its own worktree, each given its
44
66
  brief as is. Sub-agents write only in \`owns\`, never commit and never
45
67
  call Lanework. After each wave, merge, re-run each stream's checks, tick
46
- its verify steps and \`checkpoint\` once.`;
68
+ its verify steps and \`checkpoint\` once.`,
69
+ ];
@@ -20,6 +20,7 @@ import {
20
20
  import type { ToolContract } from "./schema";
21
21
 
22
22
  export * from "./board";
23
+ export * from "./instructions";
23
24
  export * from "./kit";
24
25
  export * from "./outputs";
25
26
  export * from "./schema";
@@ -0,0 +1,168 @@
1
+ // How an agent uses the board tools: the `instructions` both Lanework MCP
2
+ // servers answer `initialize` with, the cloud one (mcp.lanework.dev) and the
3
+ // desktop's offline one, word for word.
4
+ //
5
+ // One source, so the rules ship with the tools: a server update is a rules
6
+ // update, in every harness and every repo, and a project's AGENTS.md needs
7
+ // only a pointer (`AGENT_NOTES`). Both servers' parity checks compare their
8
+ // `initialize` answer with these strings.
9
+ //
10
+ // ⚠️ Constants only, never built per request: they head the model's context,
11
+ // and text that changed per call would break the client's prompt cache.
12
+
13
+ const INTRO =
14
+ "lanework is a Kanban board for AI-driven development. A card is a " +
15
+ "review checklist: decisions to approve, then verify steps to prove. ";
16
+
17
+ /** Finding the board, as far as a session with only `list_boards` can. */
18
+ const FIND_BOARD =
19
+ "Every tool needs a board_id and there is no default. A conversation " +
20
+ "the Lanework app started is told its board_id when it starts: use that " +
21
+ "one. Otherwise run `git remote get-url origin` and call " +
22
+ "list_boards({ repo }) with the output as is. Exactly one board: use it. ";
23
+
24
+ /** What a full session does when the repo has no board, or several. */
25
+ const NO_BOARD =
26
+ "None: list_boards without repo and ask which board this repo belongs to, " +
27
+ "offering also a new one (suggest `owner/name` from the remote); then " +
28
+ "link_repo their pick, or create_board only if they asked. Linking a board " +
29
+ "that has another repo MOVES the link. Several, or no remote: ask. Never " +
30
+ "pick a board by its name. ";
31
+ ("git remote: ask the user. Never pick a board by its name. ");
32
+
33
+ /** Creating a card: what every create_review must carry. */
34
+ const NEW_CARD =
35
+ "Before create_review, read board_summary and reuse its categories and " +
36
+ "tags (the category mints the task id; never invent one). Every " +
37
+ "create_review passes category, 1-3 tags and priority (high: blockers, " +
38
+ "release prerequisites; medium: planned work; low: polish). Body: context, " +
39
+ "out of scope, files touched. Checklist: decisions the user approves, " +
40
+ "verify steps that prove the work; a pick-ONE choice is boxes sharing a " +
41
+ "`group`, the recommendation marked. ";
42
+ ("here. ");
43
+
44
+ /** The gate between a card's plan and its implementation. */
45
+ const REVIEW_GATE =
46
+ "Behavior-changing work starts only once every decision is ticked; " +
47
+ "read-only requests, obvious one-file fixes and work whose exact shape the " +
48
+ "user gave need no card. toggle_item ticks boxes and notes (a verify tick " +
49
+ "sends evidence: the command and whether it passed), update_review edits " +
50
+ "metadata, set_status moves lanes. ";
51
+ ("sends evidence (the command and whether it passed). ");
52
+
53
+ const CHECKPOINT_FLOW =
54
+ "While working a card, call checkpoint after each item you finish and " +
55
+ "before you stop. To resume: get_review and read its checkpoint; if " +
56
+ "checkpoint.git.wipRef is set and this is not the checkout it came from " +
57
+ "(another host, a fresh clone, a sandbox), check out checkpoint.git.head " +
58
+ "and `git fetch origin <wipRef> && git cherry-pick --no-commit FETCH_HEAD " +
59
+ "&& git reset`. Re-run every check it claims passed, then continue from " +
60
+ "nextStep. ";
61
+ ("continue from nextStep (or the summary). ");
62
+
63
+ const STALE =
64
+ "A card with `stale` set was left mid-task: resume it from its checkpoint " +
65
+ "rather than opening a duplicate. ";
66
+ ("its checkpoint. ");
67
+
68
+ const HAND_OFF =
69
+ "Finished, verified work goes to the review-role lane via set_status; only " +
70
+ "a human moves it to done. A card sent back carries changesRequested.reason " +
71
+ "in get_review: read it first. When set_status returns retro, propose at " +
72
+ "most 3 lessons and ask before writing any. ";
73
+ ("user before writing any. ");
74
+
75
+ /** Leading a card's streams (BE-19); also the `work` prompt's text. */
76
+ export const STREAMS_FLOW =
77
+ "A card with streams comes back from get_review with `dispatch: { waves, " +
78
+ "briefs }`, and you are its lead. Run it wave by wave: spawn every stream " +
79
+ "of a wave at once, one sub-agent per stream, each in its own git worktree " +
80
+ "from the current HEAD (in the shared checkout when its isolation is " +
81
+ "shared), and hand each one `dispatch.briefs[key]` verbatim. No " +
82
+ "sub-agents? Run the streams yourself, one by one, in wave order. " +
83
+ "Sub-agents never call Lanework and never commit. After each wave, merge " +
84
+ "each worktree into the main checkout, revert anything outside the " +
85
+ "stream's `owns`, re-run the stream's checks, tick its verify items, and " +
86
+ "call checkpoint once for the wave. After the last wave, run the untagged " +
87
+ "verify items. On resume, re-dispatch only the streams whose verify items " +
88
+ "are not all ticked. A card without streams (dispatch: null) works as " +
89
+ "before: one agent, end to end.";
90
+
91
+ /** Splitting a new card into streams, when writing it. */
92
+ const WRITE_STREAMS =
93
+ "Split a card into streams only when it touches two or more independent " +
94
+ "write areas: each has a key (W0…), goal, role, exact `owns` paths no " +
95
+ "other stream in its wave owns, and a verify item tagged with its key; " +
96
+ "shared types go in a W0 the others depend on; at most 4 per wave. ";
97
+ ("on, at most 4 streams per wave. ");
98
+
99
+ /** Reviewing a card with the user (BE-14); also the `review` prompt's text. */
100
+ export const REVIEW_FLOW =
101
+ "To review a card with the user in the CLI: get_review it, then ask the " +
102
+ "user with your option picker (AskUserQuestion) if you have one. Each " +
103
+ "pick-ONE group (boxes sharing a `group`) is one single-select question, " +
104
+ "its options the group's boxes, the one marked (Recommended) first. Gather " +
105
+ "the ungrouped decisions into multi-select questions of up to 4 boxes " +
106
+ "each. At most 4 questions per turn — ask again for the rest. A group with " +
107
+ "more than 4 options cannot fit: say so and send the user to the app for " +
108
+ "that group. Then call review_card ONCE with exactly what the user picked: " +
109
+ "a picked box checked: true, an offered but unpicked ungrouped box " +
110
+ "checked: false, and anything they typed under Other as that box's note. " +
111
+ "Never tick a decision the user did not pick; only a plain instruction in " +
112
+ "chat (e.g. 'tick the recommended ones') stands in for the picker. " +
113
+ "review_card does not move the card, and work starts only once it answers " +
114
+ "ready: true.";
115
+
116
+ /**
117
+ * The streams and review flows, short, for the instructions. The full texts
118
+ * (STREAMS_FLOW, REVIEW_FLOW) stay the `work` and `review` prompts'.
119
+ *
120
+ * ⚠️ The instructions stay under 4,000 characters: Claude Code cuts a
121
+ * server's instructions at 4,096 (`… [truncated]`), and what falls past it
122
+ * is lost. `bun run check:size` in CI holds them to it.
123
+ */
124
+ const RUN_STREAMS =
125
+ "A card with streams comes back from get_review with dispatch { waves, " +
126
+ "briefs }: you are its lead. Per wave, spawn one sub-agent per stream at " +
127
+ "once (own worktree unless shared) with its brief verbatim; sub-agents " +
128
+ "never call Lanework or commit. After the wave, merge, revert anything " +
129
+ "outside each stream's owns, re-run its checks, tick its verify items, " +
130
+ "checkpoint once. Then the untagged verify items. ";
131
+
132
+ const REVIEW_SHORT =
133
+ "To review a card with the user: get_review it and ask with your option " +
134
+ "picker, one single-select question per pick-ONE group (recommended " +
135
+ "first) and the other decisions as multi-select, at most 4 questions a " +
136
+ "turn; then call review_card ONCE with exactly what they picked (unpicked " +
137
+ "offered boxes false, Other text as the note). Never tick a decision they " +
138
+ "did not pick. Work starts only once it answers ready: true.";
139
+
140
+ /** Every board tool's rules: the full toolset's `initialize` instructions. */
141
+ export const BOARD_INSTRUCTIONS =
142
+ INTRO +
143
+ FIND_BOARD +
144
+ NO_BOARD +
145
+ NEW_CARD +
146
+ REVIEW_GATE +
147
+ CHECKPOINT_FLOW +
148
+ STALE +
149
+ HAND_OFF +
150
+ WRITE_STREAMS +
151
+ RUN_STREAMS +
152
+ REVIEW_SHORT;
153
+
154
+ /**
155
+ * The worker toolset's instructions (BE-24): only what a session working
156
+ * ONE existing card needs. Sentences about tools it does not have would
157
+ * cost tokens every turn and invite calls to tools that are not there.
158
+ */
159
+ export const BOARD_WORKER_INSTRUCTIONS =
160
+ INTRO +
161
+ "This connection serves only the tools for working an existing card; " +
162
+ "creating, linking or reviewing cards needs the full lanework server. " +
163
+ FIND_BOARD +
164
+ "None, several, or no git remote: ask the user. Never pick a board by " +
165
+ "its name. Do not start a card still in todo with decisions unticked. " +
166
+ CHECKPOINT_FLOW +
167
+ HAND_OFF +
168
+ RUN_STREAMS.trimEnd();