workhorse-ai-mcp 0.8.2 → 0.8.3

package/README.md

@@ -12,6 +12,36 @@ The journal enforces a simple discipline: `DRAFT → DELEGATED → REPORTED →
 ACCEPTED | REWORK | FAILED`, where *reported* (the worker thinks it is done)
 is never the same as *accepted* (the orchestrator verified it).
 
+## Quick start
+
+**Claude Code — two commands** (installs the MCP server *and* the skill):
+
+```bash
+claude plugin marketplace add https://github.com/workhorse-ai/workhorse-ai-mcp
+claude plugin install workhorse-ai@workhorse-ai
+```
+
+**Any other agent** — install the skill, then add the MCP server to your
+agent's MCP config:
+
+```bash
+npx skills add workhorse-ai/workhorse-ai-mcp
+```
+
+```json
+{ "mcpServers": { "workhorse": { "command": "npx", "args": ["-y", "workhorse-ai-mcp"] } } }
+```
+
+Optionally, pin the rule at the project level — copy this into your
+`AGENTS.md` / `CLAUDE.md`:
+
+```markdown
+Delegation goes through the `workhorse` MCP journal. Worker duties:
+`search_precedents` before starting, `record_artifact` (progress notes)
+along the way, `submit_report` at the end. Never commit and never accept
+your own work — acceptance requires the orchestrator's own test run.
+```
+
 ## Install
 
 Add the server to your `.mcp.json`:
@@ -46,25 +76,6 @@ On first start the server creates the directory and the database itself.
 
 ## Connect to the cloud (optional)
 
-The journal works fully offline. To sync it with a Planado workspace, issue
-an MCP token on the workspace's MCP page and ask your agent to call the
-`connect` tool:
-
-```json
-connect {
-  "url": "https://<your-workspace>/api/mcp/journal-sync",
-  "token": "<mcp token>"
-}
-```
-
-`connect` verifies the connection first and only then writes `sync.json`
-next to the database — no manual configuration. The journal id defaults to
-a normalized `<username>-<hostname>`. After that, every journal write is
-auto-pushed; `sync` forces a push, and `inbox`/`take` pull task intents
-from the cloud.
-
-## Connecting to a cloud
-
 `connect` needs only a token — the managed Workhorse AI cloud is the default:
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workhorse-ai-mcp",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "private": false,
   "type": "module",
   "description": "Delegation journal for orchestrator/worker AI workflows: event sourcing over SQLite with an MCP interface. Zero dependencies.",

package/server.mjs

@@ -862,7 +862,7 @@ function handle(msg) {
 			respond(id, {
 				protocolVersion: params?.protocolVersion ?? "2024-11-05",
 				capabilities: { tools: {}, prompts: {} },
-				serverInfo: { name: "workhorse-mcp", version: "0.8.2" },
+				serverInfo: { name: "workhorse-mcp", version: "0.8.3" },
 				instructions: SERVER_INSTRUCTIONS,
 			});
 		} else if (method === "prompts/list") {

package/skills/workhorse-ai/SKILL.md

@@ -19,6 +19,31 @@ full-text search. The server validates status transitions, so you never need —
 must never try — to write to the database by hand. Do not create task files in the
 project repository: state lives in the journal only.
 
+## Requirements
+
+This skill drives the **workhorse MCP server** — without it, none of the tools
+referenced below exist. If your agent has no `workhorse` server connected, add
+it first (or ask the user to):
+
+```json
+{ "mcpServers": { "workhorse": { "command": "npx", "args": ["-y", "workhorse-ai-mcp"] } } }
+```
+
+The server needs Node.js >= 22.5, stores data in `~/.workhorse-ai/journal.db`,
+and creates the database itself on first start. It also announces its protocol
+in the MCP `initialize` instructions, so the status machine below is always
+available to the agent even without this skill.
+
+Tool inventory (names may be prefixed by your client, e.g. `mcp__workhorse__*`):
+
+| Group | Tools |
+|---|---|
+| Registry | `resolve_project`, `register_project`, `list_projects` |
+| Task lifecycle | `draft_task`, `delegate`, `submit_report`, `accept`, `request_rework`, `mark_failed` |
+| Knowledge | `search_precedents`, `record_artifact`, `record_incident`, `list_artifacts` |
+| Overview | `get_task`, `list_tasks`, `link_tasks` |
+| Cloud (optional) | `connect`, `sync`, `inbox`, `take` |
+
 ## Roles
 
 | Stage | Who | Why |
@@ -33,6 +58,22 @@ project repository: state lives in the journal only.
 A one-to-three-line fix with a diagnosis already in hand is done inline:
 delegating costs more than the edit itself.
 
+The roles are **acts, not separate programs**. Any of these configurations
+works, as long as writing the code and accepting it stay separate acts:
+
+| Configuration | Orchestrator | Worker |
+|---|---|---|
+| Two CLIs | one agent (e.g. Claude Code) | another agent (e.g. a coding CLI) |
+| One CLI | the main session | a subagent it spawns |
+| Solo | the same single agent | the same single agent |
+
+In the **solo** configuration the invariant does not disappear — it becomes a
+guard against self-deception. The rule: *the report and the acceptance are
+separate acts with separate evidence*. Set `REPORTED` when the work seems done;
+`ACCEPTED` only after a fresh, complete test run over the final state of the
+code, a line-by-line diff review against the assignment, and a `verify_commit`.
+"I just wrote this myself" is never evidence.
+
 ## Statuses and the key invariant
 
 ```
@@ -88,7 +129,7 @@ creates a new version, the old one stays in history.
 
    If the worker must judge something on its own, give it a stopping criterion
    ("found a consumer → do not delete, report back").
-4. **`delegate`** (plus launching the worker). The worker's prompt carries: the
+4. **`delegate`** (plus starting the worker — another CLI, a subagent, or, in the solo configuration, simply switching hats). The worker's prompt carries: the
    `task_id`, the assignment text, and three journal duties — `search_precedents`
    before starting; progress along the way via `record_artifact` (kind `note`, bound
    to `task_id`, with a stable `title` such as `progress: <slug>`, which versions