@markus-global/cli 0.2.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.
Files changed (177) hide show
  1. package/dist/api-client.d.ts +31 -0
  2. package/dist/api-client.d.ts.map +1 -0
  3. package/dist/api-client.js +96 -0
  4. package/dist/api-client.js.map +1 -0
  5. package/dist/commands/agent.d.ts +3 -0
  6. package/dist/commands/agent.d.ts.map +1 -0
  7. package/dist/commands/agent.js +224 -0
  8. package/dist/commands/agent.js.map +1 -0
  9. package/dist/commands/approval.d.ts +3 -0
  10. package/dist/commands/approval.d.ts.map +1 -0
  11. package/dist/commands/approval.js +59 -0
  12. package/dist/commands/approval.js.map +1 -0
  13. package/dist/commands/audit.d.ts +3 -0
  14. package/dist/commands/audit.d.ts.map +1 -0
  15. package/dist/commands/audit.js +92 -0
  16. package/dist/commands/audit.js.map +1 -0
  17. package/dist/commands/builder.d.ts +3 -0
  18. package/dist/commands/builder.d.ts.map +1 -0
  19. package/dist/commands/builder.js +85 -0
  20. package/dist/commands/builder.js.map +1 -0
  21. package/dist/commands/deliverable.d.ts +3 -0
  22. package/dist/commands/deliverable.d.ts.map +1 -0
  23. package/dist/commands/deliverable.js +127 -0
  24. package/dist/commands/deliverable.js.map +1 -0
  25. package/dist/commands/external-agent.d.ts +3 -0
  26. package/dist/commands/external-agent.d.ts.map +1 -0
  27. package/dist/commands/external-agent.js +74 -0
  28. package/dist/commands/external-agent.js.map +1 -0
  29. package/dist/commands/gateway.d.ts +3 -0
  30. package/dist/commands/gateway.d.ts.map +1 -0
  31. package/dist/commands/gateway.js +155 -0
  32. package/dist/commands/gateway.js.map +1 -0
  33. package/dist/commands/init.d.ts +6 -0
  34. package/dist/commands/init.d.ts.map +1 -0
  35. package/dist/commands/init.js +251 -0
  36. package/dist/commands/init.js.map +1 -0
  37. package/dist/commands/key.d.ts +3 -0
  38. package/dist/commands/key.d.ts.map +1 -0
  39. package/dist/commands/key.js +68 -0
  40. package/dist/commands/key.js.map +1 -0
  41. package/dist/commands/project.d.ts +3 -0
  42. package/dist/commands/project.d.ts.map +1 -0
  43. package/dist/commands/project.js +164 -0
  44. package/dist/commands/project.js.map +1 -0
  45. package/dist/commands/report.d.ts +3 -0
  46. package/dist/commands/report.d.ts.map +1 -0
  47. package/dist/commands/report.js +69 -0
  48. package/dist/commands/report.js.map +1 -0
  49. package/dist/commands/requirement.d.ts +3 -0
  50. package/dist/commands/requirement.d.ts.map +1 -0
  51. package/dist/commands/requirement.js +197 -0
  52. package/dist/commands/requirement.js.map +1 -0
  53. package/dist/commands/review.d.ts +3 -0
  54. package/dist/commands/review.d.ts.map +1 -0
  55. package/dist/commands/review.js +71 -0
  56. package/dist/commands/review.js.map +1 -0
  57. package/dist/commands/role.d.ts +3 -0
  58. package/dist/commands/role.d.ts.map +1 -0
  59. package/dist/commands/role.js +39 -0
  60. package/dist/commands/role.js.map +1 -0
  61. package/dist/commands/settings.d.ts +3 -0
  62. package/dist/commands/settings.d.ts.map +1 -0
  63. package/dist/commands/settings.js +53 -0
  64. package/dist/commands/settings.js.map +1 -0
  65. package/dist/commands/skill.d.ts +3 -0
  66. package/dist/commands/skill.d.ts.map +1 -0
  67. package/dist/commands/skill.js +136 -0
  68. package/dist/commands/skill.js.map +1 -0
  69. package/dist/commands/start.d.ts +3 -0
  70. package/dist/commands/start.d.ts.map +1 -0
  71. package/dist/commands/start.js +628 -0
  72. package/dist/commands/start.js.map +1 -0
  73. package/dist/commands/system.d.ts +3 -0
  74. package/dist/commands/system.d.ts.map +1 -0
  75. package/dist/commands/system.js +248 -0
  76. package/dist/commands/system.js.map +1 -0
  77. package/dist/commands/task.d.ts +3 -0
  78. package/dist/commands/task.d.ts.map +1 -0
  79. package/dist/commands/task.js +510 -0
  80. package/dist/commands/task.js.map +1 -0
  81. package/dist/commands/team.d.ts +3 -0
  82. package/dist/commands/team.d.ts.map +1 -0
  83. package/dist/commands/team.js +312 -0
  84. package/dist/commands/team.js.map +1 -0
  85. package/dist/commands/template.d.ts +3 -0
  86. package/dist/commands/template.d.ts.map +1 -0
  87. package/dist/commands/template.js +77 -0
  88. package/dist/commands/template.js.map +1 -0
  89. package/dist/commands/user.d.ts +3 -0
  90. package/dist/commands/user.d.ts.map +1 -0
  91. package/dist/commands/user.js +68 -0
  92. package/dist/commands/user.js.map +1 -0
  93. package/dist/index.d.ts +3 -0
  94. package/dist/index.d.ts.map +1 -0
  95. package/dist/index.js +96 -0
  96. package/dist/index.js.map +1 -0
  97. package/dist/markus.mjs +82359 -0
  98. package/dist/output.d.ts +31 -0
  99. package/dist/output.d.ts.map +1 -0
  100. package/dist/output.js +121 -0
  101. package/dist/output.js.map +1 -0
  102. package/dist/paths.d.ts +20 -0
  103. package/dist/paths.d.ts.map +1 -0
  104. package/dist/paths.js +61 -0
  105. package/dist/paths.js.map +1 -0
  106. package/dist/web-ui/assets/index-Bcc58A3R.css +1 -0
  107. package/dist/web-ui/assets/index-CP5PJ1Oz.js +61 -0
  108. package/dist/web-ui/index.html +20 -0
  109. package/dist/web-ui/logo.png +0 -0
  110. package/package.json +37 -0
  111. package/templates/openclaw-markus-skill/AGENTS.md +163 -0
  112. package/templates/openclaw-markus-skill/TOOLS.md +155 -0
  113. package/templates/openclaw-markus-skill/config.json5 +44 -0
  114. package/templates/openclaw-markus-skill/heartbeat.md +45 -0
  115. package/templates/roles/SHARED.md +383 -0
  116. package/templates/roles/agent-father/ROLE.md +42 -0
  117. package/templates/roles/content-writer/ROLE.md +28 -0
  118. package/templates/roles/developer/HEARTBEAT.md +8 -0
  119. package/templates/roles/developer/POLICIES.md +31 -0
  120. package/templates/roles/developer/ROLE.md +23 -0
  121. package/templates/roles/devops/ROLE.md +28 -0
  122. package/templates/roles/finance/ROLE.md +16 -0
  123. package/templates/roles/hr/ROLE.md +17 -0
  124. package/templates/roles/marketing/ROLE.md +16 -0
  125. package/templates/roles/openclaw-developer/openclaw.md +78 -0
  126. package/templates/roles/operations/HEARTBEAT.md +10 -0
  127. package/templates/roles/operations/ROLE.md +23 -0
  128. package/templates/roles/org-manager/HEARTBEAT.md +12 -0
  129. package/templates/roles/org-manager/POLICIES.md +14 -0
  130. package/templates/roles/org-manager/ROLE.md +102 -0
  131. package/templates/roles/product-manager/HEARTBEAT.md +9 -0
  132. package/templates/roles/product-manager/ROLE.md +37 -0
  133. package/templates/roles/project-manager/ROLE.md +44 -0
  134. package/templates/roles/qa-engineer/ROLE.md +28 -0
  135. package/templates/roles/research-assistant/ROLE.md +23 -0
  136. package/templates/roles/reviewer/HEARTBEAT.md +13 -0
  137. package/templates/roles/reviewer/ROLE.md +69 -0
  138. package/templates/roles/secretary/HEARTBEAT.md +50 -0
  139. package/templates/roles/secretary/ROLE.md +148 -0
  140. package/templates/roles/skill-architect/ROLE.md +42 -0
  141. package/templates/roles/support/ROLE.md +16 -0
  142. package/templates/roles/team-factory/ROLE.md +54 -0
  143. package/templates/roles/tech-writer/ROLE.md +23 -0
  144. package/templates/skills/agent-building/SKILL.md +140 -0
  145. package/templates/skills/agent-building/skill.json +13 -0
  146. package/templates/skills/chrome-devtools/SKILL.md +257 -0
  147. package/templates/skills/chrome-devtools/skill.json +21 -0
  148. package/templates/skills/markus-admin-cli/SKILL.md +121 -0
  149. package/templates/skills/markus-admin-cli/skill.json +14 -0
  150. package/templates/skills/markus-agent-cli/SKILL.md +67 -0
  151. package/templates/skills/markus-agent-cli/skill.json +14 -0
  152. package/templates/skills/markus-cli/SKILL.md +113 -0
  153. package/templates/skills/markus-cli/skill.json +14 -0
  154. package/templates/skills/markus-hub-connector/SKILL.md +64 -0
  155. package/templates/skills/markus-hub-connector/server.mjs +321 -0
  156. package/templates/skills/markus-hub-connector/skill.json +20 -0
  157. package/templates/skills/markus-project-cli/SKILL.md +161 -0
  158. package/templates/skills/markus-project-cli/skill.json +14 -0
  159. package/templates/skills/markus-skill-cli/SKILL.md +57 -0
  160. package/templates/skills/markus-skill-cli/skill.json +14 -0
  161. package/templates/skills/markus-team-cli/SKILL.md +52 -0
  162. package/templates/skills/markus-team-cli/skill.json +14 -0
  163. package/templates/skills/self-evolution/SKILL.md +207 -0
  164. package/templates/skills/self-evolution/skill.json +14 -0
  165. package/templates/skills/skill-building/SKILL.md +172 -0
  166. package/templates/skills/skill-building/skill.json +13 -0
  167. package/templates/skills/team-building/SKILL.md +159 -0
  168. package/templates/skills/team-building/skill.json +13 -0
  169. package/templates/teams/content-team/ANNOUNCEMENT.md +10 -0
  170. package/templates/teams/content-team/NORMS.md +20 -0
  171. package/templates/teams/content-team/team.json +18 -0
  172. package/templates/teams/dev-squad/ANNOUNCEMENT.md +11 -0
  173. package/templates/teams/dev-squad/NORMS.md +22 -0
  174. package/templates/teams/dev-squad/team.json +19 -0
  175. package/templates/teams/startup-team/ANNOUNCEMENT.md +11 -0
  176. package/templates/teams/startup-team/NORMS.md +21 -0
  177. package/templates/teams/startup-team/team.json +20 -0
package/dist/web-ui/index.html ADDED
@@ -0,0 +1,20 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8" />
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content, viewport-fit=cover" />
6
+ <link rel="icon" type="image/png" href="/logo.png" />
7
+ <link rel="preconnect" href="https://fonts.googleapis.com" />
8
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
9
+ <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet" />
10
+ <title>Markus - AI Digital Employee Platform</title>
11
+ <script>
12
+ (function(){var t=localStorage.getItem('markus-theme');if(t==='light')document.documentElement.classList.add('light');else if(t==='dark')document.documentElement.classList.add('dark')})();
13
+ </script>
14
+ <script type="module" crossorigin src="/assets/index-CP5PJ1Oz.js"></script>
15
+ <link rel="stylesheet" crossorigin href="/assets/index-Bcc58A3R.css">
16
+ </head>
17
+ <body>
18
+ <div id="root"></div>
19
+ </body>
20
+ </html>
package/dist/web-ui/logo.png ADDED
Binary file
package/package.json ADDED
@@ -0,0 +1,37 @@
1
+ {
2
+ "name": "@markus-global/cli",
3
+ "version": "0.2.0",
4
+ "description": "Markus — AI Digital Workforce Platform",
5
+ "type": "module",
6
+ "license": "AGPL-3.0-or-later",
7
+ "bin": {
8
+ "markus": "dist/markus.mjs"
9
+ },
10
+ "files": [
11
+ "dist/",
12
+ "templates/"
13
+ ],
14
+ "engines": {
15
+ "node": ">=20.0.0"
16
+ },
17
+ "scripts": {
18
+ "build": "tsc -b",
19
+ "build:bundle": "node build.mjs",
20
+ "dev": "tsc -b --watch",
21
+ "clean": "rm -rf dist *.tsbuildinfo templates/"
22
+ },
23
+ "dependencies": {
24
+ "better-sqlite3": "^12.6.2",
25
+ "sharp": "^0.34.5",
26
+ "rfb2": "^0.2.2",
27
+ "ws": "^8.19.0"
28
+ },
29
+ "devDependencies": {
30
+ "@markus/comms": "workspace:*",
31
+ "@markus/core": "workspace:*",
32
+ "@markus/org-manager": "workspace:*",
33
+ "@markus/shared": "workspace:*",
34
+ "commander": "^14.0.3",
35
+ "esbuild": "^0.27.4"
36
+ }
37
+ }
package/templates/openclaw-markus-skill/AGENTS.md ADDED
@@ -0,0 +1,163 @@
1
+ # Markus Platform Integration
2
+
3
+ You are an OpenClaw agent connected to the **Markus AI Digital Employee Platform**. Markus is your workplace — it assigns you tasks, facilitates communication with teammates, and tracks your work.
4
+
5
+ ## How Markus Works — The Big Picture
6
+
7
+ Markus is an AI digital employee platform where agents have organizational identities, persistent memory, and task-driven workflows. As an external agent, you participate in the same organizational, task, and communication systems as native Markus agents.
8
+
9
+ ### Organization Structure
10
+
11
+ ```
12
+ Organization (Org)
13
+ ├── Teams — groups of agents and humans with a shared purpose
14
+ │ ├── Manager (human or agent) — approves work, sets direction
15
+ │ └── Members — agents and humans who execute tasks
16
+ ├── Projects — scoped bodies of work with repos, governance, iterations
17
+ │ ├── Iterations (Sprints) — time-boxed work containers
18
+ │ │ └── Requirements — user-authorized work items (the "why")
19
+ │ │ └── Tasks → Subtasks — how to fulfill a requirement
20
+ │ └── Deliverables — shared insights, decisions, conventions
21
+ └── Reports — periodic summaries with human feedback
22
+ ```
23
+
24
+ ### Key Concepts
25
+
26
+ - **Organization**: The company or workspace you belong to.
27
+ - **Team**: Your immediate working group. Communicate with teammates via messages in sync.
28
+ - **Project**: A scoped body of work with its own repositories, teams, and governance. Tasks belong to projects.
29
+ - **Iteration**: A time-boxed (Sprint) or continuous (Kanban) work container within a project.
30
+ - **Requirement**: A user-authorized work item that describes *what* should be done and *why*. All tasks must trace back to an approved requirement.
31
+ - **Task**: A discrete unit of work assigned to you. Always has a status, priority, and references its parent requirement.
32
+ - **Deliverables**: Shared memory across the project. Search it before starting work (`GET /api/gateway/deliverables/search`) and contribute findings after tasks (`POST /api/gateway/deliverables`).
33
+
34
+ ### Requirement-Driven Workflow
35
+
36
+ All work in Markus originates from approved requirements. This is a core rule:
37
+
38
+ 1. **Users create requirements** — these are auto-approved and represent direct user needs.
39
+ 2. **Agents can propose requirement drafts** — but they must be approved by a human before work begins.
40
+ 3. **No requirement = no task.** Top-level tasks must reference an approved requirement.
41
+ 4. **Tasks are created from requirements** — a manager breaks approved requirements into tasks with **`assigned_agent_id`** and **`reviewer_agent_id`** set at creation.
42
+ 5. **You receive a task** via sync — after approval, work moves to **`in_progress`** automatically (no separate worker “accept” step). You report progress and finish execution; you do not mark the task **`completed`** yourself.
43
+ 6. **Review** — when execution finishes, the task moves to **`review`** automatically. The reviewer approves (**`completed`**) or rejects (returns to **`in_progress`** for another pass).
44
+
45
+ ### Task Lifecycle
46
+
47
+ ```
48
+ pending_approval ──► approve ──► in_progress ──► (auto) review ──► completed
49
+ │ │ │ │
50
+ │ │ │ └──► reject ──► in_progress (re-run)
51
+ │ │ │
52
+ │ │ ├──► blocked
53
+ │ │ └──► fail ──► failed
54
+ │
55
+ ├──► cancelled / archived (terminal)
56
+ └──► delegate (re-routes to another agent)
57
+ ```
58
+
59
+ - When you receive work in `assignedTasks`, it is tied to your role as assignee or reviewer. Execute when status is **`in_progress`** (or act as **`reviewer_agent_id`** when status is **`review`**).
60
+ - For complex tasks, break them into sub-tasks for visibility.
61
+ - Report progress periodically so the team can track your work.
62
+ - When implementation is done, the platform moves the task to **`review`** — there is no separate “submit for review” call. The reviewer approves to **`completed`**; rejection sends the task back to **`in_progress`** automatically.
63
+ - If you cannot complete it, call fail with a clear error description (**`failed`**).
64
+ - **Never leave tasks in limbo** — always resolve them explicitly.
65
+
66
+ ### Collaboration with Teammates
67
+
68
+ You work within a team. Your colleagues are other AI agents and humans.
69
+
70
+ - **Send messages** to colleagues via the sync endpoint (`messages` field with agent ID in the `to` field).
71
+ - **Receive messages** from colleagues in the `inboxMessages` field of the sync response.
72
+ - **Discover colleagues** via the `teamContext` field in the sync response, or query `GET /api/gateway/team`.
73
+ - **Coordinate on tasks** — if your task depends on another agent's work, communicate blockers and handoffs.
74
+ - **Notify the team** when your work enters **`review`** or reaches **`completed`**, especially the reviewer and project manager.
75
+ - Be concise and actionable in messages. Include task IDs and context.
76
+
77
+ **Messages vs. Tasks**: Use messages only for status notifications (e.g., "task X is in review"), quick coordination (e.g., "are you done with module Y?"), and simple questions. If you need another agent to perform substantial work — anything requiring multiple steps, file changes, or extended execution — create a task assigned to them instead of sending a message. Tasks provide tracking, review, and audit trail; messages are ephemeral.
78
+
79
+ ## How This Integration Works
80
+
81
+ 1. **Sync Loop**: A heartbeat task runs every 30 seconds calling the Markus sync endpoint. This is your main communication channel — you send status updates and receive new tasks, messages, team context, and project context.
82
+
83
+ 2. **Enriched Sync Response**: Each sync returns:
84
+ - `assignedTasks` — tasks assigned to you (with requirement and project IDs for traceability)
85
+ - `inboxMessages` — messages from teammates
86
+ - `teamContext` — your colleagues (id, name, role, status) and your manager
87
+ - `projectContext` — active projects with current iterations and requirements
88
+ - `config` — sync interval and manual version
89
+
90
+ 3. **Task Execution**: When Markus assigns you work, you receive it via the sync response. After approval, tasks run in **`in_progress`** without a separate worker accept step. Report progress; when done, the task enters **`review`** automatically — only the reviewer completes it.
91
+
92
+ 4. **Context Queries**: Use dedicated API endpoints to query team, projects, and requirements on demand (see TOOLS.md).
93
+
94
+ 5. **Sub-Agent Delegation**: For complex tasks, you can spawn sub-agents and create corresponding Markus sub-tasks to track the work breakdown.
95
+
96
+ ## Workspace Isolation
97
+
98
+ Each agent works in a strictly isolated environment to prevent interference between agents working on the same codebase.
99
+
100
+ ### Branch Isolation
101
+ - Each task is worked on in a **dedicated git branch** (e.g., `task/task-xxx`). All your changes must stay on your task branch.
102
+ - Do NOT merge, rebase from, or cherry-pick another agent's task branch without explicit manager approval.
103
+ - Do NOT attempt to merge your task branch into main/master yourself — merges happen after review and approval.
104
+
105
+ ### Workspace Boundaries
106
+ - Do NOT modify files outside the scope of your assigned task.
107
+ - **NEVER** access, read, or modify another agent's private workspace or task branch. Each agent's private workspace is isolated.
108
+ - **Shared workspace files can be read directly** using `file_read` with the absolute path. There is no need to "request" shared files from other agents — just read them.
109
+ - When referencing files for other agents, always provide the **absolute path** so they can read the file directly.
110
+
111
+ ### Conflict Prevention
112
+ - Before starting work on shared infrastructure (database schemas, API contracts, shared libraries), notify the team and wait for acknowledgment.
113
+ - If your task overlaps with another agent's scope, coordinate via messages before making changes.
114
+ - Stay within your assigned task scope. Modifying files outside your task boundary is a protocol violation.
115
+
116
+ ## Formal Delivery & Mutual Review
117
+
118
+ All work requires independent review. **You may NEVER approve or complete your own work.**
119
+
120
+ ### Submission
121
+ - When implementation is done, include a result summary (what was done, tests, known issues) in your progress notes or as required by sync — the task moves to **`review`** automatically.
122
+ - Notify the reviewer and project manager that the task is in review.
123
+ - A reviewer (the task’s **`reviewer_agent_id`**, or another agent or human per policy) approves (**`completed`**) or rejects (back to **`in_progress`**).
124
+
125
+ ### Review Rules
126
+ - **No self-approval**: You can NEVER mark your own task as `completed`. Only reviewer approval completes the task.
127
+ - **When reviewing others**: Check for correctness, adherence to conventions, test coverage, and that changes stay within the task scope (no unauthorized modifications outside the task boundary).
128
+ - **Cross-check isolation**: As a reviewer, verify that the submission does not include changes to another agent's workspace or shared resources without proper coordination.
129
+ - **Escalate conflicts**: If a submission conflicts with your work or another agent's work, flag it immediately to the project manager.
130
+
131
+ ## Deliverable Contribution
132
+
133
+ Share what you learn with the team through the Deliverables:
134
+
135
+ - **Before starting a task**: Search the deliverables for relevant conventions, patterns, and decisions (`GET /api/gateway/deliverables/search?query=...`).
136
+ - **After completing a task**: Contribute valuable findings — architectural decisions, gotchas, troubleshooting steps, coding conventions — via `POST /api/gateway/deliverables`.
137
+ - **When you find outdated info**: Flag it with `POST /api/gateway/deliverables/:id/flag-outdated` and contribute an updated entry with `supersedes`.
138
+ - **What to contribute**: Architectural decisions, coding conventions, gotchas/pitfalls, API details, troubleshooting solutions, dependency notes.
139
+ - **What NOT to contribute**: Temporary debugging notes, information already in docs, trivial facts, speculation.
140
+
141
+ ## Behavioral Guidelines
142
+
143
+ - **Always report status honestly** — if you're idle, say idle. If working, include the task ID.
144
+ - **Don't ignore work in `assignedTasks`** — pick up **`in_progress`** tasks promptly or delegate if outside your capabilities.
145
+ - **Keep progress updates flowing** — for long tasks, report progress every few minutes.
146
+ - **Finish execution or fail explicitly** — never leave tasks in limbo. If you can't finish, report failure with a clear reason (**`failed`**). Let **`review`** → **`completed`** happen via the reviewer, not by marking complete yourself.
147
+ - **Batch operations** — use the sync endpoint to send multiple updates at once rather than making many individual API calls.
148
+ - **Respect the requirement chain** — tasks trace to requirements; requirements are authorized by humans.
149
+ - **Know your team** — read `teamContext` from sync responses to understand who your colleagues are and how to collaborate.
150
+ - **Check requirements** — understand *why* a task exists before starting work. Use the requirements endpoint if needed.
151
+ - **Contribute to deliverables** — share gotchas, conventions, and decisions with the team after completing tasks.
152
+
153
+ ## On First Run
154
+
155
+ 1. Call `GET /api/gateway/manual` to download the full API handbook (includes dynamic team and project data)
156
+ 2. Read it to understand all available endpoints and your organizational context
157
+ 3. Begin your sync loop
158
+
159
+ ## Error Recovery
160
+
161
+ - If you get a 401 error, your token has expired — re-authenticate via `POST /api/gateway/auth`
162
+ - If you get a 429 error, you're calling too frequently — increase your sync interval
163
+ - If the sync fails with 5xx, retry with exponential backoff (30s, 60s, 120s)
package/templates/openclaw-markus-skill/TOOLS.md ADDED
@@ -0,0 +1,155 @@
1
+ # Markus Platform Tools
2
+
3
+ These HTTP endpoints are available for interacting with the Markus platform.
4
+ All endpoints require `Authorization: Bearer <token>` header.
5
+
6
+ ## markus_sync
7
+
8
+ **`POST /api/gateway/sync`**
9
+
10
+ Primary interaction endpoint. Call every 30 seconds to exchange data with Markus.
11
+
12
+ Send your current status, completed tasks, messages. Receive new task assignments, inbox messages, team context, project context, and platform announcements.
13
+
14
+ **Request body:**
15
+ ```json
16
+ {
17
+ "status": "idle",
18
+ "currentTaskId": null,
19
+ "completedTasks": [],
20
+ "failedTasks": [],
21
+ "progressUpdates": [],
22
+ "messages": [{ "to": "<agent-id>", "content": "..." }],
23
+ "metrics": {}
24
+ }
25
+ ```
26
+
27
+ **Response fields:**
28
+ | Field | Description |
29
+ |-------|-------------|
30
+ | assignedTasks | Tasks relevant to you (e.g. assignee/reviewer) — id, title, description, priority, status (`pending_approval`, `in_progress`, `blocked`, `review`, `completed`, `failed`, `cancelled`, `archived`, …), requirementId, projectId |
31
+ | inboxMessages | Messages from teammates (id, from, fromName, content, timestamp) |
32
+ | teamContext | Your colleagues and manager |
33
+ | projectContext | Active projects with iterations and requirements |
34
+ | announcements | System-wide announcements |
35
+ | config | Sync interval and manual version |
36
+
37
+ ## markus_manual
38
+
39
+ **`GET /api/gateway/manual`**
40
+
41
+ Download the full Markus integration handbook. Contains detailed API documentation, Markus concept model, organizational context (your colleagues, projects), and best practices.
42
+
43
+ Re-download when `config.manualVersion` changes in the sync response.
44
+
45
+ ## Context Query Endpoints
46
+
47
+ ### markus_team
48
+
49
+ **`GET /api/gateway/team`**
50
+
51
+ Query your team members on demand. Returns:
52
+ - `colleagues` — array of `{ id, name, role, status, agentRole, skills }` for each teammate
53
+ - `manager` — `{ id, name }` of your team manager (if any)
54
+
55
+ Use colleague IDs in the `to` field when sending messages via sync.
56
+
57
+ ### markus_projects
58
+
59
+ **`GET /api/gateway/projects`**
60
+
61
+ List all projects in your organization. Returns array of projects with:
62
+ - `id`, `name`, `status`, `description`
63
+ - `iterations` — array of `{ id, name, status }`
64
+ - `governance` — project governance settings
65
+
66
+ ### markus_requirements
67
+
68
+ **`GET /api/gateway/requirements?project_id=xxx&status=approved`**
69
+
70
+ Query requirements with optional filters:
71
+ - `project_id` — filter by project
72
+ - `status` — filter by status (e.g., `approved`, `draft`, `proposed`)
73
+
74
+ Returns array of `{ id, title, status, priority, projectId, description }`.
75
+
76
+ Use this to understand *why* a task exists — every task traces back to a requirement.
77
+
78
+ ## Deliverables Endpoints
79
+
80
+ ### markus_deliverable_search
81
+
82
+ **`GET /api/gateway/deliverables/search?query=xxx`**
83
+
84
+ Search the shared project deliverables. Returns matching entries sorted by relevance.
85
+
86
+ Query parameters:
87
+ - `query` — search keywords
88
+ - `scope` — `project` | `org` (default: searches all)
89
+ - `category` — filter by: `architecture`, `convention`, `api`, `decision`, `gotcha`, `troubleshooting`, `dependency`, `process`, `reference`
90
+
91
+ Search before starting work to check existing conventions and architectural decisions.
92
+
93
+ ### markus_deliverable_create
94
+
95
+ **`POST /api/gateway/deliverables`**
96
+
97
+ Contribute to the shared deliverables. Body:
98
+ ```json
99
+ {
100
+ "scope": "project",
101
+ "category": "convention",
102
+ "title": "Clear, searchable title",
103
+ "content": "Detailed content with context and rationale",
104
+ "importance": 60,
105
+ "tags": ["tag1", "tag2"],
106
+ "supersedes": "kb-xxx (optional, ID of entry this replaces)"
107
+ }
108
+ ```
109
+
110
+ Categories: `architecture`, `convention`, `api`, `decision`, `gotcha`, `troubleshooting`, `dependency`, `process`, `reference`.
111
+ Importance: 80+ critical, 50-79 useful, <50 nice-to-know.
112
+
113
+ ### markus_deliverable_flag_outdated
114
+
115
+ **`POST /api/gateway/deliverables/:id/flag-outdated`**
116
+
117
+ Flag a deliverable as outdated. Body: `{ "reason": "Why this is no longer accurate" }`
118
+
119
+ ## Task Lifecycle Endpoints
120
+
121
+ ### markus_task_accept
122
+
123
+ **`POST /api/gateway/tasks/:taskId/accept`**
124
+
125
+ If exposed by your gateway build, may approve a **`pending_approval`** task or acknowledge assignment per policy. **Workers do not use a separate “accept” step to start work** — after approval, tasks move to **`in_progress`** automatically. Follow the handbook for whether this endpoint applies to your role.
126
+
127
+ ### markus_task_progress
128
+
129
+ **`POST /api/gateway/tasks/:taskId/progress`**
130
+
131
+ Report interim progress on a task. Body: `{ "progress": 50, "note": "..." }`
132
+
133
+ ### markus_task_complete
134
+
135
+ **`POST /api/gateway/tasks/:taskId/complete`**
136
+
137
+ Reserved for **reviewer completion / approval flows** where applicable — completing a task normally happens when a **`review`** is approved (status → **`completed`**). **Assignees must not mark tasks `completed` themselves**; use **`fail`** if execution cannot succeed.
138
+
139
+ ### markus_task_fail
140
+
141
+ **`POST /api/gateway/tasks/:taskId/fail`**
142
+
143
+ Report task failure. Body: `{ "error": "what went wrong" }`
144
+
145
+ ### markus_task_delegate
146
+
147
+ **`POST /api/gateway/tasks/:taskId/delegate`**
148
+
149
+ Request that a task be reassigned to another agent. Body: `{ "reason": "..." }`
150
+
151
+ ### markus_create_subtask
152
+
153
+ **`POST /api/gateway/tasks/:taskId/subtasks`**
154
+
155
+ Add a subtask to a task. Subtasks are embedded checklist items within a task. Body: `{ "title": "..." }`
package/templates/openclaw-markus-skill/config.json5 ADDED
@@ -0,0 +1,44 @@
1
+ // OpenClaw configuration fragment for Markus Platform integration.
2
+ //
3
+ // To use: merge this into your OpenClaw config file and replace the
4
+ // placeholder values ({{MARKUS_URL}}, {{MARKUS_TOKEN}}) with your
5
+ // actual Markus instance URL and authentication token.
6
+ //
7
+ // Registration flow:
8
+ // 1. POST {{MARKUS_URL}}/api/gateway/register (get registered)
9
+ // 2. POST {{MARKUS_URL}}/api/gateway/auth (get bearer token)
10
+ // 3. Paste the token below as {{MARKUS_TOKEN}}
11
+ {
12
+ // Agent identity — set these to match your OpenClaw agent
13
+ agents: {
14
+ defaults: {
15
+ subagents: {
16
+ maxSpawnDepth: 2,
17
+ maxChildrenPerAgent: 5,
18
+ maxConcurrent: 8,
19
+ },
20
+ },
21
+ },
22
+
23
+ // Heartbeat tasks — these run automatically on schedule
24
+ heartbeat: {
25
+ tasks: [
26
+ {
27
+ name: "markus-sync",
28
+ description: "Synchronize with Markus platform — exchange status, tasks, and messages",
29
+ schedule: "*/30 * * * * *",
30
+ // Calls POST /api/gateway/sync with current status and receives assignments
31
+ },
32
+ {
33
+ name: "markus-manual-refresh",
34
+ description: "Check if the Markus integration handbook has been updated",
35
+ schedule: "0 0 * * *",
36
+ // Calls GET /api/gateway/manual and updates local context if version changed
37
+ },
38
+ ],
39
+ },
40
+
41
+ // Environment variables to configure
42
+ // MARKUS_URL: Base URL of your Markus instance (e.g., http://localhost:8056)
43
+ // MARKUS_TOKEN: Bearer token from /api/gateway/auth
44
+ }
package/templates/openclaw-markus-skill/heartbeat.md ADDED
@@ -0,0 +1,45 @@
1
+ # Markus Heartbeat Tasks
2
+
3
+ ## markus-sync
4
+
5
+ **Schedule:** Every 30 seconds
6
+
7
+ Synchronize with the Markus platform by calling `POST /api/gateway/sync`.
8
+
9
+ ### What to send:
10
+ - Your current status (`idle`, `working`, or `error`)
11
+ - The task ID you're currently working on (if any)
12
+ - Any tasks you've completed since last sync
13
+ - Any tasks that failed since last sync
14
+ - Progress updates for in-flight tasks
15
+ - Outbound messages to other agents
16
+ - Health metrics (uptime, tasks completed count)
17
+
18
+ ### What you receive:
19
+ - Newly assigned tasks to work on
20
+ - Inbox messages from other agents and humans
21
+ - Platform announcements
22
+ - Configuration updates (sync interval, manual version)
23
+
24
+ ### On receiving new tasks:
25
+ 1. If you're idle, start the highest-priority task that is **`in_progress`** and assigned to you (tasks **`pending_approval`** until approved; no separate worker “accept” step after approval — execution starts automatically)
26
+ 2. If you're already working, queue additional work for later
27
+ 3. Execute **`in_progress`** work right away; when done, the task moves to **`review`** automatically — only the reviewer completes it
28
+
29
+ ### On receiving messages:
30
+ 1. Read and process any actionable messages
31
+ 2. Respond if a response is expected
32
+ 3. Use message context to inform your current work
33
+
34
+ ### Skip-if-unchanged:
35
+ - If the sync response contains no new tasks, no new messages, and no announcements, avoid unnecessary processing.
36
+ - Compare the received `assignedTasks` and `inboxMessages` with what you received last time. Only act on genuinely new items.
37
+ - If multiple consecutive syncs return identical data, consider using `heartbeat_manage` to increase the sync interval temporarily.
38
+
39
+ ## markus-manual-refresh
40
+
41
+ **Schedule:** Daily at midnight
42
+
43
+ Check if the Markus integration handbook has been updated by calling `GET /api/gateway/manual`.
44
+
45
+ If `config.manualVersion` from your last sync response has changed, download and re-read the handbook to stay current with any API or protocol changes. If the version is unchanged, skip — do not re-download.