npm - @markus-global/cli - Versions diffs - 0.4.20 → 0.4.22 - Mend

@markus-global/cli 0.4.20 → 0.4.22

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 (17) hide show

package/dist/commands/start.js +2 -0
package/dist/commands/start.js.map +1 -1
package/dist/markus.mjs +1657 -1053
package/dist/web-ui/assets/index-DEkXd9d7.css +1 -0
package/dist/web-ui/assets/index-HAWGXtTM.js +66 -0
package/dist/web-ui/index.html +2 -2
package/package.json +1 -1
package/templates/roles/SHARED.md +7 -6
package/templates/roles/org-manager/HEARTBEAT.md +1 -1
package/templates/roles/secretary/HEARTBEAT.md +1 -1
package/templates/skills/agent-building/SKILL.md +5 -5
package/templates/skills/markitdown/SKILL.md +56 -0
package/templates/skills/markitdown/skill.json +20 -0
package/templates/skills/self-evolution/SKILL.md +43 -7
package/templates/skills/team-building/SKILL.md +4 -5
package/dist/web-ui/assets/index-Bm8JwOPl.js +0 -66
package/dist/web-ui/assets/index-CRfXZ2wF.css +0 -1

package/dist/web-ui/index.html CHANGED Viewed

@@ -11,8 +11,8 @@
     <script>
       (function(){var t=localStorage.getItem('markus-theme');if(t&&t!=='system')document.documentElement.classList.add(t)})();
     </script>
-    <script type="module" crossorigin src="/assets/index-Bm8JwOPl.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-CRfXZ2wF.css">
+    <script type="module" crossorigin src="/assets/index-HAWGXtTM.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-DEkXd9d7.css">
   </head>
   <body>
     <div id="root"></div>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@markus-global/cli",
-  "version": "0.4.20",
+  "version": "0.4.22",
   "description": "Markus — AI Digital Workforce Platform",
   "type": "module",
   "license": "AGPL-3.0-or-later",

package/templates/roles/SHARED.md CHANGED Viewed

@@ -299,20 +299,21 @@ Your team maintains two tiers of persistent information:
 - This is YOUR private workspace — other agents cannot see it
 ### Shared Deliverables
-- Use `deliverable_create` to publish outputs that benefit the team: files, architectural decisions, conventions, gotchas, troubleshooting tips
+- **Workflow**: Write the actual content to a file FIRST (using `shell_execute` or file tools), then call `deliverable_create` to register it — the `summary` field is a brief description, NOT the full content
 - Use `deliverable_search` to find existing team outputs before starting work
 - Use `deliverable_list` to browse what's available by project, type, or agent
-- Use `deliverable_update` to flag outdated entries or update metadata
+- Use `deliverable_update` to update metadata (title, summary, status, tags) — to change the actual content, modify the file directly first
+- If the same `reference` path already exists, `deliverable_create` will update the existing record instead of creating a duplicate
-### When to Publish Deliverables
-- After completing a task, publish what you learned if it would save others time
+### When to Register Deliverables
+- After completing a task, register your output files so teammates can discover them
 - Document architectural decisions, coding patterns, API details, dependency quirks
 - Share troubleshooting steps, gotchas, and best practices
-- Create reports summarizing research or analysis findings
+- Register reports summarizing research or analysis findings
 ### Quality Guidelines
 - Write clear, searchable titles
-- Include context and rationale, not just facts
+- Summary should explain what the deliverable is and why it matters (1-3 paragraphs)
 - Tag deliverables for discoverability
 - Flag outdated entries when you find stale information

package/templates/roles/org-manager/HEARTBEAT.md CHANGED Viewed

@@ -7,7 +7,7 @@
 - **Review duty (PRIORITY)**: Use `task_list` to find tasks in `review` status where you are the designated reviewer. For each one, use `task_get` to inspect deliverables, then either approve (`task_update` with status `completed` and a review note) or reject (`task_update` with status `in_progress` and a note explaining what must change — this sends the task back for revision with a new execution round). Do NOT delay — unreviewed tasks block your team.
 - Check for tasks in `pending` — approve or reject promptly so work is not stalled.
 - **Failed task recovery**: Check `task_list` for tasks assigned to you with status `failed`. If found, retry by calling `task_update(status: "in_progress")` with a note — this auto-restarts execution.
-- **Daily report (after 20:00 only)**: The system will tell you if a report is due. If the "Daily Report Required" section appears in the prompt, produce the report via `deliverable_create`. The report must be concise (<500 words), timestamped, and cover: your work, team progress, blockers, and tomorrow's priorities. Do NOT create the report before 20:00.
+- **Daily report (after 20:00 only)**: The system will tell you if a report is due. If the "Daily Report Required" section appears in the prompt, write the report content to a file first (using `shell_execute`), then register it via `deliverable_create` with a brief summary. The report must be concise (<500 words), timestamped, and cover: your work, team progress, blockers, and tomorrow's priorities. Do NOT create the report before 20:00.
 - **Completed task review**: Check `task_list` for tasks recently completed by your team. For each:
   - What went well? (first-pass approvals, smooth coordination, clean delegation)
   - What management patterns worked? (task decomposition, reviewer assignment, workload balancing)

package/templates/roles/secretary/HEARTBEAT.md CHANGED Viewed

@@ -63,6 +63,6 @@ Skip if nothing meaningful happened.
 ## Daily Report (after 20:00 only)
-The system will tell you if a report is due. If the "Daily Report Required" section appears in the prompt, produce the report via `deliverable_create`. The report must be concise (<500 words), timestamped, and cover: your work, team progress, blockers, and tomorrow's priorities. Do NOT create the report before 20:00.
+The system will tell you if a report is due. If the "Daily Report Required" section appears in the prompt, write the report content to a file first (using `shell_execute`), then register it via `deliverable_create` with a brief summary. The report must be concise (<500 words), timestamped, and cover: your work, team progress, blockers, and tomorrow's priorities. Do NOT create the report before 20:00.
 - If nothing changed since last summary, respond HEARTBEAT_OK.

package/templates/skills/agent-building/SKILL.md CHANGED Viewed

@@ -21,7 +21,7 @@ This skill teaches you how to create Markus agent packages — self-contained di
 **Do NOT write artifacts to `~/.markus/shared/`, your working directory, or any other location.** Only `~/.markus/builder-artifacts/agents/` is recognized by the system.
-When the user **installs** the artifact, files are deployed to `~/.markus/agents/{agentId}/role/`. The `ROLE.md` is loaded as the agent's system prompt and **overrides** the base role template's default prompt.
+When the user **installs** the artifact, files are deployed to `~/.markus/agents/{agentId}/role/`. The `ROLE.md` becomes the agent's system prompt — it IS the agent's identity, not an override of a template.
 ## Two-Step Workflow
@@ -55,7 +55,6 @@ This JSON contains ONLY metadata — **no file content**.
     "env": ["git", "node"]
   },
   "agent": {
-    "roleName": "developer",
     "agentRole": "manager | worker",
     "llmProvider": "anthropic | openai | google | (empty for default)",
     "llmModel": "model name or empty for default",
@@ -109,13 +108,14 @@ file_write("~/.markus/builder-artifacts/agents/code-reviewer/POLICIES.md", "# Po
 - **`dependencies.env`**: Required CLI tools (e.g., `["git", "node"]`). Omit if none needed.
 ### `agent` section (REQUIRED)
-- **`roleName`**: Base role template from the dynamic context. Determines default tools. Use `developer` as fallback.
 - **`agentRole`**: `"worker"` (executes tasks) or `"manager"` (coordinates, assigns, reviews)
 - **`llmProvider`**, **`llmModel`**, **`temperature`**: LLM configuration. Leave empty for system defaults.
+**Note**: The `roleName` field is **not needed**. The agent's identity is fully defined by its `ROLE.md` file. Do NOT include `roleName` unless you specifically want to inherit default tools from a built-in role template (rare).
 ## Tool Access Philosophy
-**All agents have access to all tools provided by their role template.** Security is controlled through the agent's `ROLE.md` and `POLICIES.md`, not through tool restrictions.
+**All agents have access to all built-in tools.** Security is controlled through the agent's `ROLE.md` and `POLICIES.md`, not through tool restrictions.
 If an agent needs to be cautious with certain tools, write that into `POLICIES.md`:
 - "Only use `shell_execute` for read-only commands unless explicitly asked"
@@ -134,7 +134,7 @@ Once all files are written, tell the user:
 ## Rules
-- **DO NOT** invent role names or skill IDs. Only use values from the dynamic context.
+- **DO NOT** invent skill IDs. Only use values from the dynamic context.
 - **DO NOT** put file content in the JSON. Always use `file_write` for files.
 - **DO NOT** default skills to `[]` when relevant skills are available. Check the skills list!
 - **DO NOT** write artifacts to `~/.markus/shared/` or your working directory. Always use `~/.markus/builder-artifacts/agents/{name}/`.

package/templates/skills/markitdown/SKILL.md ADDED Viewed

@@ -0,0 +1,56 @@
+---
+name: markitdown
+description: Convert documents (PDF, Word, Excel, PowerPoint, images) to Markdown text for LLM processing
+---
+# MarkItDown File Converter
+You have access to the MarkItDown MCP tool (`markitdown__convert_to_markdown`) for converting files to Markdown.
+## When to use
+Use this tool when:
+- The user asks you to read, analyze, or summarize a document (PDF, Word, Excel, PowerPoint, etc.)
+- You need to extract text content from an image (OCR)
+- The user shares a file path and wants you to understand its contents
+- You are working with a file format that your text tools cannot directly read
+**Note:** For images attached directly in chat, the system automatically handles conversion when your model doesn't support vision. This skill is for converting files on disk that you encounter during tasks.
+## Supported formats
+MarkItDown supports 29+ file formats including:
+- **Documents**: PDF, Word (.docx), PowerPoint (.pptx), Excel (.xlsx/.xls)
+- **Images**: JPEG, PNG, GIF, WebP (EXIF metadata + OCR)
+- **Web**: HTML, XML
+- **Data**: CSV, JSON
+- **Other**: ZIP (iterates contents), EPUB, Outlook messages (.msg)
+## Usage
+```
+markitdown__convert_to_markdown({ uri: "file:///path/to/document.pdf" })
+```
+The tool accepts a file URI and returns the content converted to Markdown format.
+## Prerequisites
+MarkItDown requires Python 3.10+ and the `markitdown` package:
+```bash
+pip install 'markitdown[all]'
+```
+Or install only specific format support:
+```bash
+pip install 'markitdown[pdf,docx,pptx]'
+```
+## Best practices
+1. **Check file existence first**: Verify the file path is valid before attempting conversion.
+2. **Large files**: For very large documents, the converted markdown may be lengthy. Summarize key sections for the user rather than dumping everything.
+3. **Image OCR quality**: OCR results depend on image clarity. Mention if text extraction seems incomplete.
+4. **Fallback**: If conversion fails (e.g., markitdown not installed), inform the user and suggest installing with `pip install 'markitdown[all]'`.

package/templates/skills/markitdown/skill.json ADDED Viewed

@@ -0,0 +1,20 @@
+{
+  "type": "skill",
+  "name": "markitdown",
+  "displayName": "MarkItDown File Converter",
+  "version": "1.0.0",
+  "description": "Convert documents (PDF, Word, Excel, PowerPoint, images) to Markdown text for LLM processing",
+  "author": "markus",
+  "category": "data",
+  "tags": ["ocr", "pdf", "document", "conversion", "multimodal"],
+  "skill": {
+    "skillFile": "SKILL.md",
+    "requiredPermissions": ["file"],
+    "mcpServers": {
+      "markitdown": {
+        "command": "uvx",
+        "args": ["markitdown-mcp"]
+      }
+    }
+  }
+}

package/templates/skills/self-evolution/SKILL.md CHANGED Viewed

@@ -42,7 +42,8 @@ Skip trivial matters — typos, one-off path errors, situations that won't recur
 | Validated pattern from successful task | Observation buffer | `memory_save` with tags: `["insight", ...]` |
 | Multi-step repeatable workflow (personal) | MEMORY.md | `memory_update_longterm({ section: "<your-section>", mode: "patch" })` |
 | Practice worth sharing with the team | Skill package | Create via **skill-building**, install with `builder_install` |
-| 3+ related insights → behavioral rule | ROLE.md | Read → append → log change |
+| Behavioral rule or guiding principle | ROLE.md | `file_read` → `file_edit` to append |
+| New recurring check for your patrol | HEARTBEAT.md | `file_read` → `file_edit` to add/remove items |
 ## Capturing Insights (Observation Buffer)
@@ -166,12 +167,23 @@ Only create a skill when you are confident the practice is validated (proven acr
 ## Role Evolution (ROLE.md)
-The deepest level. Modify ROLE.md only when ALL conditions are met:
+ROLE.md is your identity — it is loaded into every conversation and shapes all your behavior. Updating it is one of the **simplest and most impactful** forms of self-evolution.
-1. **Pattern threshold** — 3+ related insights pointing to a fundamental behavioral change
-2. **High confidence** — Proven by successfully completed tasks
-3. **Systemic impact** — Affects many future tasks
-4. **Not contradicting core role** — Refines or extends, doesn't contradict
+### When to Update
+Modify ROLE.md when you discover a behavioral rule, working style, or guiding principle that should **always** apply to your work. Examples:
+- "Always run tests before submitting code for review"
+- "When debugging, check logs first before reading source code"
+- "Prefer small, focused PRs over large ones"
+You do NOT need to accumulate multiple insights first — even a single validated lesson can warrant a role update if it is fundamental and non-obvious.
+### Guard Rails
+- **Refine, don't contradict** — New guidelines should extend your core role, not conflict with it
+- **Proven, not speculative** — The principle should be validated by actual task outcomes
+- **Not one-off** — It should apply to future tasks, not just the current situation
 ### How to Modify
@@ -180,13 +192,37 @@ The deepest level. Modify ROLE.md only when ALL conditions are met:
 3. Use `file_edit` for surgical changes
 4. Log: `memory_save` with tags `["insight", "role-evolution"]`
+## Heartbeat Customization (HEARTBEAT.md)
+HEARTBEAT.md is your personal patrol checklist — it controls what you check during each heartbeat cycle. Customizing it is a direct way to evolve your operational behavior.
+### When to Update
+- You realize you should be regularly checking for something you currently aren't (e.g., monitoring a specific service, reviewing a certain type of task)
+- A checklist item is obsolete or no longer relevant to your responsibilities
+- You want to change the order or priority of your patrol routine
+### How to Modify
+1. Read current HEARTBEAT.md via `file_read`
+2. Add, remove, or reorder checklist items via `file_edit`
+3. Changes take effect at the next heartbeat cycle (the system auto-reloads)
+4. Log: `memory_save` with tags `["insight", "heartbeat-evolution"]`
+### Examples of Good Heartbeat Additions
+- "Check if any PR I opened has new review comments"
+- "Verify that the staging deployment matches the latest main branch"
+- "Review `task_list` for tasks blocked more than 24 hours — escalate if needed"
 ## Quality Signal
 During heartbeat, check your revision rate:
 - Tasks with `executionRound > 1` required revision
 - High revision rate (>30%) means your knowledge isn't being applied effectively
 - Check if saved insights cover the failure patterns you see
-- Escalate recurring mistakes: insight → MEMORY.md procedure → role update
+- Consider: would a ROLE.md rule or a HEARTBEAT.md check have prevented any recent failures?
+- Escalate recurring mistakes: insight → MEMORY.md procedure → ROLE.md rule or HEARTBEAT.md check
 ## Rules

package/templates/skills/team-building/SKILL.md CHANGED Viewed

@@ -37,7 +37,7 @@ This skill teaches you how to create Markus team packages — self-contained dir
 |---|---|---|
 | `ANNOUNCEMENT.md` | `~/.markus/teams/{teamId}/ANNOUNCEMENT.md` | Injected into every member's context |
 | `NORMS.md` | `~/.markus/teams/{teamId}/NORMS.md` | Injected into every member's context |
-| `members/{name}/ROLE.md` | `~/.markus/agents/{agentId}/role/ROLE.md` | Overrides base role template prompt |
+| `members/{name}/ROLE.md` | `~/.markus/agents/{agentId}/role/ROLE.md` | Agent's identity and system prompt |
 | `members/{name}/POLICIES.md` | `~/.markus/agents/{agentId}/role/POLICIES.md` | Additional agent constraints |
 ## Two-Step Workflow
@@ -72,14 +72,12 @@ This JSON contains ONLY metadata and structure — **no file content**.
       {
         "name": "Manager Name",
         "role": "manager",
-        "roleName": "project-manager",
         "count": 1,
         "skills": ["skill-id-1"]
       },
       {
         "name": "Worker Name",
         "role": "worker",
-        "roleName": "developer",
         "count": 1,
         "skills": ["skill-id-1", "skill-id-2"]
       }
@@ -148,10 +146,11 @@ file_write("~/.markus/builder-artifacts/teams/research-team/members/senior-resea
 ### `team.members[]` — Member Specifications (REQUIRED)
 - **`name`**: Display name (the slug for file paths is derived from this)
 - **`role`**: `"manager"` or `"worker"`
-- **`roleName`**: Base role template from the dynamic context
 - **`count`**: Number of instances (default 1)
 - **`skills`**: Skill IDs from the dynamic context. **Actively assign skills — don't leave empty!**
+**Note**: The `roleName` field is **not needed** for team members. Each member's identity is fully defined by their `ROLE.md` file under `members/{slug}/`. Do NOT include `roleName` unless you specifically want to inherit defaults from a built-in role template (rare).
 ### `team.workflow` — Workflow Configuration (recommended)
 - **`phases`**: Array of phase names defining the team's workflow (e.g., `["plan", "implement", "review", "validate"]`)
 - **`parallelImplementation`**: `true` if multiple members work in parallel during implementation
@@ -170,7 +169,7 @@ Once all files are written, tell the user:
 ## Rules
-- **DO NOT** invent role names or skill IDs. Only use values from the dynamic context.
+- **DO NOT** invent skill IDs. Only use values from the dynamic context.
 - **DO NOT** leave skills empty when relevant skills are available. Review the skills list!
 - **DO NOT** put file content in the JSON. Always use `file_write` for files.
 - **DO NOT** write artifacts to `~/.markus/shared/` or your working directory. Always use `~/.markus/builder-artifacts/teams/{name}/`.