@lanework/contracts 0.3.0 → 0.4.0

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.0",
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",
@@ -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,153 @@
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: call list_boards without repo and ask the user which board this " +
27
+ "repo belongs to — the boards you can see, PLUS an option to create a " +
28
+ "new board for this repo (suggest `owner/name` from the remote as its " +
29
+ "name). Then link_repo the one they picked, or create_board if they " +
30
+ "chose a new one; never create a board they did not ask for. A board " +
31
+ "links to ONE repo: linking a board that already has another repo " +
32
+ "MOVES it (replace), it never adds a second. Several: ask the user. No " +
33
+ "git remote: ask the user. Never pick a board by its name. ";
34
+
35
+ /** Creating a card: what every create_review must carry. */
36
+ const NEW_CARD =
37
+ "Before creating a card, read board_summary so its category and tags " +
38
+ "match the vocabulary the board already uses; the category is also what " +
39
+ "mints the card's permanent task id. Every create_review (a successor " +
40
+ "card too) passes category, 1-3 tags and priority explicitly: high for " +
41
+ "blockers and release prerequisites, medium for planned work, low for " +
42
+ "polish. Put context, an out-of-scope section and the files touched in " +
43
+ "the body; decisions the user approves and verify steps that prove the " +
44
+ "work in the checklist, a pick-ONE choice as boxes sharing a `group` " +
45
+ "with the recommendation marked. Never invent a task id: the server " +
46
+ "mints it. After create_review, offer to review the new card right " +
47
+ "here. ";
48
+
49
+ /** The gate between a card's plan and its implementation. */
50
+ const REVIEW_GATE =
51
+ "Behavior-changing work starts only once every decision box is ticked " +
52
+ "(a card in todo with decisions open is a plan, not a go). Read-only " +
53
+ "requests, single-file obvious fixes, or work whose exact shape the user " +
54
+ "gave need no card. Use toggle_item for checklist boxes and notes, " +
55
+ "update_review for metadata, set_status for lanes; ticking a verify item " +
56
+ "sends evidence (the command and whether it passed). ";
57
+
58
+ const CHECKPOINT_FLOW =
59
+ "While working a card, call checkpoint after each checklist item you " +
60
+ "finish and before you stop mid-task. Asked to resume a card: " +
61
+ "get_review it and read its checkpoint. If checkpoint.git.wipRef is " +
62
+ "set AND you are not in the checkout it came from (checkpoint.host " +
63
+ "is another machine, or this is a fresh clone or a cloud sandbox), " +
64
+ "check out checkpoint.git.head, then `git fetch origin <wipRef> && " +
65
+ "git cherry-pick --no-commit FETCH_HEAD && git reset` to restore the " +
66
+ "uncommitted work; in the same checkout that work is already on " +
67
+ "disk, so skip it. Re-run every check it claims passed, then " +
68
+ "continue from nextStep (or the summary). ";
69
+
70
+ const STALE =
71
+ "A card with `stale` set was left mid-task by another agent: before " +
72
+ "opening a new card for the same work, get_review it and resume from " +
73
+ "its checkpoint. ";
74
+
75
+ const HAND_OFF =
76
+ "Finished and verified work goes to the board's review-role lane via " +
77
+ "set_status, not done; only a human moves it to done. A card sent " +
78
+ "back from review carries changesRequested.reason in get_review: " +
79
+ "read it first. " +
80
+ "When set_status returns retro, propose at most 3 lessons and ask the " +
81
+ "user before writing any. ";
82
+
83
+ /** Leading a card's streams (BE-19); also the `work` prompt's text. */
84
+ export const STREAMS_FLOW =
85
+ "A card with streams comes back from get_review with `dispatch: { waves, " +
86
+ "briefs }`, and you are its lead. Run it wave by wave: spawn every stream " +
87
+ "of a wave at once, one sub-agent per stream, each in its own git worktree " +
88
+ "from the current HEAD (in the shared checkout when its isolation is " +
89
+ "shared), and hand each one `dispatch.briefs[key]` verbatim. No " +
90
+ "sub-agents? Run the streams yourself, one by one, in wave order. " +
91
+ "Sub-agents never call Lanework and never commit. After each wave, merge " +
92
+ "each worktree into the main checkout, revert anything outside the " +
93
+ "stream's `owns`, re-run the stream's checks, tick its verify items, and " +
94
+ "call checkpoint once for the wave. After the last wave, run the untagged " +
95
+ "verify items. On resume, re-dispatch only the streams whose verify items " +
96
+ "are not all ticked. A card without streams (dispatch: null) works as " +
97
+ "before: one agent, end to end.";
98
+
99
+ /** Splitting a new card into streams, when writing it. */
100
+ const WRITE_STREAMS =
101
+ "Split a card into streams only when it touches two or more independent " +
102
+ "write areas: each stream has a key (W0, W1…), a goal, a role and exact " +
103
+ "`owns` paths no other stream in its wave owns, and at least one verify " +
104
+ "item tagged with its key; shared types go in a W0 the others depend " +
105
+ "on, at most 4 streams per wave. ";
106
+
107
+ /** Reviewing a card with the user (BE-14); also the `review` prompt's text. */
108
+ export const REVIEW_FLOW =
109
+ "To review a card with the user in the CLI: get_review it, then ask the " +
110
+ "user with your option picker (AskUserQuestion) if you have one. Each " +
111
+ "pick-ONE group (boxes sharing a `group`) is one single-select question, " +
112
+ "its options the group's boxes, the one marked (Recommended) first. Gather " +
113
+ "the ungrouped decisions into multi-select questions of up to 4 boxes " +
114
+ "each. At most 4 questions per turn — ask again for the rest. A group with " +
115
+ "more than 4 options cannot fit: say so and send the user to the app for " +
116
+ "that group. Then call review_card ONCE with exactly what the user picked: " +
117
+ "a picked box checked: true, an offered but unpicked ungrouped box " +
118
+ "checked: false, and anything they typed under Other as that box's note. " +
119
+ "Never tick a decision the user did not pick; only a plain instruction in " +
120
+ "chat (e.g. 'tick the recommended ones') stands in for the picker. " +
121
+ "review_card does not move the card, and work starts only once it answers " +
122
+ "ready: true.";
123
+
124
+ /** Every board tool's rules: the full toolset's `initialize` instructions. */
125
+ export const BOARD_INSTRUCTIONS =
126
+ INTRO +
127
+ FIND_BOARD +
128
+ NO_BOARD +
129
+ NEW_CARD +
130
+ REVIEW_GATE +
131
+ CHECKPOINT_FLOW +
132
+ STALE +
133
+ HAND_OFF +
134
+ WRITE_STREAMS +
135
+ STREAMS_FLOW +
136
+ " " +
137
+ REVIEW_FLOW;
138
+
139
+ /**
140
+ * The worker toolset's instructions (BE-24): only what a session working
141
+ * ONE existing card needs. Sentences about tools it does not have would
142
+ * cost tokens every turn and invite calls to tools that are not there.
143
+ */
144
+ export const BOARD_WORKER_INSTRUCTIONS =
145
+ INTRO +
146
+ "This connection serves only the tools for working an existing card; " +
147
+ "creating, linking or reviewing cards needs the full lanework server. " +
148
+ FIND_BOARD +
149
+ "None, several, or no git remote: ask the user. Never pick a board by " +
150
+ "its name. Do not start a card still in todo with decisions unticked. " +
151
+ CHECKPOINT_FLOW +
152
+ HAND_OFF +
153
+ STREAMS_FLOW;