@markus-global/cli 0.8.1 → 0.8.2

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

@@ -21,6 +21,8 @@ This skill teaches you how to create Markus team packages — self-contained dir
 ├── README.md                    # Public-facing team overview for Hub/Builder (REQUIRED)
 ├── ANNOUNCEMENT.md              # Team announcement (you write via file_write)
 ├── NORMS.md                     # Working norms (you write via file_write)
+├── workflows/                   # Workflow templates (optional)
+│   └── {workflow-name}.yaml     # YAML workflow DAG definition
 └── members/
     ├── {manager-slug}/
     │   ├── ROLE.md              # Identity and system prompt (REQUIRED)
@@ -46,10 +48,11 @@ This skill teaches you how to create Markus team packages — self-contained dir
 | `members/{name}/HEARTBEAT.md` | `~/.markus/agents/{agentId}/role/HEARTBEAT.md` | Periodic self-check checklist (every ~30 min) |
 | `members/{name}/POLICIES.md` | `~/.markus/agents/{agentId}/role/POLICIES.md` | Additional agent constraints |
 | `members/{name}/CONTEXT.md` | `~/.markus/agents/{agentId}/role/CONTEXT.md` | Domain context and references |
+| `workflows/*.yaml` | `~/.markus/teams/{teamId}/workflows/*.yaml` | Workflow templates (runnable as task DAGs) |
 
-## Two-Step Workflow
+## Creation Workflow
 
-Output the team in two steps — manifest first, then content files. **Never put file content inline in the JSON.**
+Output the team in up to three steps — manifest first, then content files, then optional workflow YAML. **Never put file content inline in the JSON.**
 
 ### Chat Mode vs Task Mode
 
@@ -94,7 +97,8 @@ This JSON contains ONLY metadata and structure — **no file content**.
       "parallelImplementation": true,
       "worktreeIsolation": true,
       "requireReviewBeforeComplete": true
-    }
+    },
+    "workflows": ["workflows/my-workflow.yaml"]
   }
 }
 ```
@@ -157,6 +161,65 @@ file_write("~/.markus/builder-artifacts/teams/research-team/members/senior-resea
 
 **IMPORTANT**: The member directory slug is derived from the member's `name` field — lowercased, spaces to hyphens, non-alphanumeric removed.
 
+### Step 3: Write Workflow YAML (optional)
+
+If the team has repeatable multi-step processes that should run as automated DAGs, add workflow templates. Each workflow is a YAML file that defines a sequence of tasks with dependencies, role assignments, and optional scheduling.
+
+**When to include workflows:**
+- The team has a process that runs repeatedly (e.g., weekly content publishing, daily reports)
+- Multiple members need to collaborate in a defined sequence
+- You want steps to run in parallel where possible and wait on dependencies automatically
+
+**Write each workflow YAML to `workflows/`:**
+
+```
+file_write("~/.markus/builder-artifacts/teams/{team-name}/workflows/content-publishing.yaml", "<YAML content>")
+```
+
+Make sure `team.workflows` in your manifest references the file:
+```json
+"workflows": ["workflows/content-publishing.yaml"]
+```
+
+**Minimal workflow example:**
+
+```yaml
+name: content-publishing
+displayName: Content Publishing
+description: Plan, write, and review content
+version: "1.0.0"
+
+params:
+  - name: topic
+    type: string
+    required: true
+
+steps:
+  - id: plan
+    name: Plan Content
+    type: agent_task
+    role: editor
+    prompt: "Create a content plan for: {{topic}}"
+
+  - id: write
+    name: Write Draft
+    type: agent_task
+    role: writer
+    depends_on: [plan]
+    inputs: [{ from: plan, as: content_plan }]
+    prompt: "Write content about {{topic}} following the plan."
+
+  - id: review
+    name: Review & Publish
+    type: agent_task
+    role: editor
+    depends_on: [write]
+    inputs: [{ from: write, as: draft }]
+    prompt: "Review the draft and finalize for publishing."
+```
+
+For the full YAML format reference, DAG patterns, scheduling, and more examples, activate the **`workflow-building`** skill.
+
 ## Field Reference
 
 ### Top-level fields
@@ -182,6 +245,11 @@ file_write("~/.markus/builder-artifacts/teams/research-team/members/senior-resea
 - **`worktreeIsolation`**: `true` if developers should work in isolated git worktrees (recommended for coding teams)
 - **`requireReviewBeforeComplete`**: `true` if tasks must pass review before completion
 
+### `team.workflows` — Workflow Template Files (optional)
+- Array of YAML file paths relative to the package root, e.g. `["workflows/content-publishing.yaml"]`
+- These files are copied to `~/.markus/teams/{teamId}/workflows/` on install and become runnable via the Workflows UI or `workflow_run` tool
+- See the `workflow-building` skill for the full YAML format
+
 ## After Creation
 
 > **CRITICAL**: Creating an artifact is NOT the same as installing/deploying it. Creating writes files to `builder-artifacts/`; installing deploys live agents that consume resources and join the org. **NEVER auto-install.** Only install when the user explicitly says "install", "deploy", or "hire". This applies to ALL modes (chat, task, A2A).
@@ -199,6 +267,7 @@ Once all files are written, tell the user:
 - **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}/`.
 - **The `name` field MUST be English kebab-case**.
+- **All top-level fields must be the correct type**: `author` must be a plain string (e.g. `"John"`) — NOT an object. `tags` must be an array of strings. `version` must be semver string. `description` must be a string. The system validates the manifest on write and will reject malformed files.
 - Every team MUST have exactly **one** member with `"role": "manager"` and at least **one** `"worker"`.
 - Write each ROLE.md with **full attention** — at least 5 substantive paragraphs per member.
 - Do NOT rush through members. Each one deserves careful, tailored content.

package/templates/skills/workflow-building/SKILL.md

@@ -0,0 +1,467 @@
+---
+name: workflow-building
+description: Design and create workflow templates — YAML format, DAG patterns, scheduling, and role mapping
+---
+
+# Workflow Building
+
+This skill teaches you how to create **workflow templates** — YAML-based definitions of multi-step processes that are executed as a DAG (Directed Acyclic Graph) of tasks. Each step is assigned to a team member by role and runs automatically with dependency tracking.
+
+## When to Use Workflows
+
+Workflows are for **repeatable, multi-step processes** where:
+- Multiple agents need to collaborate in a defined sequence
+- Steps have clear dependencies (B waits for A to finish)
+- The same process runs repeatedly with different parameters
+- You want automatic scheduling (daily, weekly, etc.)
+
+**Do NOT use workflows for**: one-off tasks, simple single-agent work, or ad-hoc coordination.
+
+## How to Create Workflows
+
+There are two ways to create a workflow, depending on context:
+
+### For an existing (live) team
+
+Use the `workflow_create` tool:
+```
+workflow_create(name: "content-publishing", yaml: "<full YAML content>")
+```
+This writes the YAML file directly to `~/.markus/teams/{teamId}/workflows/`.
+
+### For a team package (builder artifact)
+
+Write the YAML file via `file_write` to the team's artifact directory, then reference it in `team.json`:
+
+```
+file_write("~/.markus/builder-artifacts/teams/{team-name}/workflows/my-workflow.yaml", "<YAML content>")
+```
+
+In `team.json`, add:
+```json
+{
+  "team": {
+    "members": [...],
+    "workflows": ["workflows/my-workflow.yaml"]
+  }
+}
+```
+
+The workflow YAML files are copied to `~/.markus/teams/{teamId}/workflows/` when the team is installed.
+
+## YAML Format Reference
+
+### Top-Level Fields
+
+```yaml
+name: content-publishing           # REQUIRED. Identifier (kebab-case, English)
+displayName: Content Publishing    # Optional. Human-readable name (any language)
+description: Research, write, ...  # REQUIRED. What this workflow does
+version: "1.0.0"                   # REQUIRED. Semver
+
+schedule:                          # Optional. Auto-trigger configuration
+  every: "1d"                      #   Interval shorthand: 30m, 6h, 1d, 1w
+  cron: "0 9 * * 1-5"             #   OR cron expression
+  run_at: "2025-06-01T09:00:00Z"  #   OR one-shot ISO timestamp
+  timezone: "Asia/Shanghai"        #   IANA timezone (default: server local)
+  max_runs: 10                     #   Stop after N runs (0 = unlimited)
+
+params:                            # Optional. User-provided or auto-generated inputs
+  - name: topic                    #   Referenced as {{topic}} in step prompts
+    type: string                   #   string | enum | text | agent
+    label: "Content Topic"
+    required: true
+  - name: platform
+    type: enum
+    options: ["wechat", "zhihu", "xiaohongshu", "x.com"]
+    default: "wechat"
+
+steps:                             # REQUIRED. The task DAG (at least one step)
+  - id: research
+    name: Research Topic
+    type: agent_task
+    role: researcher
+    prompt: "Research {{topic}} thoroughly and produce a summary."
+    priority: high
+```
+
+### Step Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `id` | Yes | Unique identifier within the workflow |
+| `name` | Yes | Human-readable step name |
+| `type` | Yes | Always `agent_task` |
+| `role` | Yes | Role placeholder mapped to a team member at run time |
+| `prompt` | Yes | Task description. Supports `{{param}}` interpolation |
+| `depends_on` | No | Array of step IDs that must complete first |
+| `inputs` | No | Upstream deliverable references (see below) |
+| `reviewer` | No | Role that reviews this step (defaults to team manager) |
+| `priority` | No | `low`, `medium`, `high`, or `urgent` |
+| `timeout` | No | Step timeout shorthand, e.g. `"30m"`, `"2h"` |
+| `retry_count` | No | Number of retries on failure (default: 0) |
+
+### Parameter Types
+
+| Type | Description |
+|------|-------------|
+| `string` | Free-form text input |
+| `enum` | Dropdown selection from `options[]` |
+| `text` | Multi-line text input |
+| `agent` | Agent ID picker |
+
+### Built-in Template Variables
+
+These are available in all step prompts without declaring params:
+- `{{date}}` — Current date (YYYY-MM-DD)
+- `{{time}}` — Current date and time (YYYY-MM-DD HH:MM)
+- `{{run_number}}` — Sequential run number for this workflow
+
+### Upstream Inputs
+
+When a step depends on another step's output, use `inputs` to create a named reference:
+
+```yaml
+steps:
+  - id: research
+    name: Research
+    type: agent_task
+    role: researcher
+    prompt: "Research {{topic}} and produce a summary document."
+
+  - id: write
+    name: Write Draft
+    type: agent_task
+    role: writer
+    depends_on: [research]
+    inputs:
+      - from: research       # Step ID of the upstream step
+        as: research_notes    # Variable name in this step's context
+    prompt: "Write a draft about {{topic}} using the upstream research."
+```
+
+The system automatically injects context about upstream deliverables into the step's prompt. The downstream agent can use `task_get` to retrieve the upstream step's full deliverables.
+
+## DAG Design Patterns
+
+### Linear Chain
+
+Steps run one after another. Simple and predictable.
+
+```yaml
+# A → B → C
+steps:
+  - id: research
+    name: Research
+    type: agent_task
+    role: researcher
+    prompt: "Research the topic."
+
+  - id: write
+    name: Write
+    type: agent_task
+    role: writer
+    depends_on: [research]
+    prompt: "Write based on research."
+
+  - id: review
+    name: Review
+    type: agent_task
+    role: editor
+    depends_on: [write]
+    prompt: "Review and finalize the draft."
+```
+
+### Fan-Out (Parallel)
+
+Multiple independent steps run simultaneously after a shared predecessor.
+
+```yaml
+#        ┌→ write_cn
+# plan ──┤
+#        └→ write_en
+steps:
+  - id: plan
+    name: Plan Content
+    type: agent_task
+    role: editor
+    prompt: "Create content outline for {{topic}}."
+
+  - id: write_cn
+    name: Write Chinese Version
+    type: agent_task
+    role: chinese_writer
+    depends_on: [plan]
+    inputs: [{ from: plan, as: outline }]
+    prompt: "Write the Chinese version based on the outline."
+
+  - id: write_en
+    name: Write English Version
+    type: agent_task
+    role: english_writer
+    depends_on: [plan]
+    inputs: [{ from: plan, as: outline }]
+    prompt: "Write the English version based on the outline."
+```
+
+### Fan-In (Aggregation)
+
+One step waits for multiple parallel steps to complete.
+
+```yaml
+#  write_cn ──┐
+#             ├→ publish
+#  write_en ──┘
+steps:
+  # ... (plan, write_cn, write_en as above)
+
+  - id: publish
+    name: Final Review & Publish
+    type: agent_task
+    role: editor
+    depends_on: [write_cn, write_en]
+    inputs:
+      - { from: write_cn, as: chinese_draft }
+      - { from: write_en, as: english_draft }
+    prompt: "Review both drafts and prepare for publishing."
+```
+
+### Diamond
+
+Combination of fan-out and fan-in — a common pattern for parallel work with consolidation.
+
+```yaml
+#        ┌→ B ──┐
+#  A ────┤      ├→ D
+#        └→ C ──┘
+```
+
+## Role Design
+
+Roles are **placeholders** that get mapped to actual team members at run time. The system auto-resolves roles by matching role names to agent names, skills, or role types.
+
+**Best practices:**
+- Use descriptive role names that match your team composition: `editor`, `chinese_writer`, `researcher`, `reviewer`
+- Each role should map to a distinct team member or function
+- The `reviewer` field defaults to the team manager — only override if a specific specialist should review
+- Keep role names consistent across workflows in the same team
+
+## Schedule Configuration
+
+### Interval-Based
+
+```yaml
+schedule:
+  every: "6h"        # Run every 6 hours
+  timezone: "Asia/Shanghai"
+```
+
+Supported units: `s` (seconds), `m` (minutes), `h` (hours), `d` (days), `w` (weeks).
+
+### Cron-Based
+
+```yaml
+schedule:
+  cron: "0 9 * * 1-5"   # Weekdays at 9am
+  timezone: "Asia/Shanghai"
+```
+
+Standard 5-field cron: minute, hour, day-of-month, month, day-of-week.
+
+### One-Shot
+
+```yaml
+schedule:
+  run_at: "2025-07-01T09:00:00+08:00"
+```
+
+Fires once at the specified time, then stops.
+
+## Complete Examples
+
+### Example 1: Content Publishing Pipeline
+
+A 4-step pipeline for a content team: plan → parallel writing → review.
+
+```yaml
+name: content-publishing
+displayName: Content Publishing Pipeline
+description: Plan content, write in parallel across platforms, then review and publish
+version: "1.0.0"
+
+params:
+  - name: topic
+    type: string
+    label: Content Topic
+    required: true
+    description: The main topic or theme for this content batch
+  - name: target_platforms
+    type: text
+    label: Target Platforms
+    default: "WeChat, Xiaohongshu, X.com"
+
+steps:
+  - id: plan
+    name: Content Planning
+    type: agent_task
+    role: editor
+    priority: high
+    prompt: |
+      Create a detailed content plan for: {{topic}}
+      Target platforms: {{target_platforms}}
+
+      Produce:
+      1. Content angle and key messages
+      2. Platform-specific adaptation notes
+      3. Target audience for each platform
+      4. SEO keywords / hashtags
+
+  - id: write_chinese
+    name: Write Chinese Content
+    type: agent_task
+    role: chinese_writer
+    depends_on: [plan]
+    inputs: [{ from: plan, as: content_plan }]
+    prompt: |
+      Write Chinese content about {{topic}} following the content plan.
+      Produce drafts for WeChat public account and Zhihu.
+
+  - id: write_xhs
+    name: Write Xiaohongshu Notes
+    type: agent_task
+    role: xhs_operator
+    depends_on: [plan]
+    inputs: [{ from: plan, as: content_plan }]
+    prompt: |
+      Create Xiaohongshu notes about {{topic}} following the content plan.
+      Produce 2-3 note drafts with title, body, hashtags, and image descriptions.
+
+  - id: review_and_publish
+    name: Editorial Review
+    type: agent_task
+    role: editor
+    depends_on: [write_chinese, write_xhs]
+    inputs:
+      - { from: write_chinese, as: chinese_drafts }
+      - { from: write_xhs, as: xhs_drafts }
+    prompt: |
+      Review all content drafts for {{topic}}.
+      Check for consistency, quality, and brand voice alignment.
+      Provide final approval or revision notes for each piece.
+```
+
+### Example 2: Research Report
+
+A linear pipeline: research → analyze → write report.
+
+```yaml
+name: research-report
+displayName: Research & Report
+description: Deep research on a topic, data analysis, and formatted report
+version: "1.0.0"
+
+params:
+  - name: research_question
+    type: text
+    label: Research Question
+    required: true
+  - name: depth
+    type: enum
+    options: ["brief", "standard", "deep-dive"]
+    default: "standard"
+
+steps:
+  - id: research
+    name: Gather Sources
+    type: agent_task
+    role: researcher
+    priority: high
+    timeout: "2h"
+    prompt: |
+      Research: {{research_question}}
+      Depth level: {{depth}}
+
+      Gather information from multiple sources. Save key findings,
+      data points, and source references as deliverables.
+
+  - id: analyze
+    name: Analyze Findings
+    type: agent_task
+    role: analyst
+    depends_on: [research]
+    inputs: [{ from: research, as: raw_findings }]
+    prompt: |
+      Analyze the research findings for: {{research_question}}
+      Identify patterns, insights, and actionable conclusions.
+      Produce a structured analysis document.
+
+  - id: report
+    name: Write Final Report
+    type: agent_task
+    role: writer
+    depends_on: [analyze]
+    inputs: [{ from: analyze, as: analysis }]
+    prompt: |
+      Write a comprehensive report on: {{research_question}}
+      Use the analysis to structure the report with:
+      - Executive summary
+      - Key findings
+      - Detailed analysis
+      - Recommendations
+      Format as a polished HTML deliverable.
+```
+
+### Example 3: Scheduled Daily Digest
+
+An automatically triggered daily workflow.
+
+```yaml
+name: daily-digest
+displayName: Daily Content Digest
+description: Automatically gather and summarize daily updates
+version: "1.0.0"
+
+schedule:
+  cron: "0 9 * * 1-5"
+  timezone: "Asia/Shanghai"
+
+steps:
+  - id: gather
+    name: Gather Updates
+    type: agent_task
+    role: researcher
+    prompt: |
+      Gather today's updates and news for {{date}}.
+      Check industry trends, competitor activity, and team progress.
+
+  - id: summarize
+    name: Write Daily Summary
+    type: agent_task
+    role: writer
+    depends_on: [gather]
+    inputs: [{ from: gather, as: updates }]
+    prompt: |
+      Write a concise daily digest for {{date}} (run #{{run_number}}).
+      Summarize the key updates and highlight action items.
+```
+
+## Validation Rules
+
+The system validates your YAML before saving. Common errors:
+- **Missing required fields**: `name`, `description`, `version`, and at least one step
+- **Each step requires**: `id`, `name`, `role`, `prompt`
+- **Duplicate step IDs**: every `id` must be unique
+- **Invalid `depends_on` references**: must reference existing step IDs
+- **Circular dependencies**: the DAG must be acyclic (A→B→C→A is invalid)
+- **Enum params without options**: `type: enum` requires a non-empty `options[]`
+- **Invalid schedule**: must have at least one of `every`, `cron`, or `run_at`
+
+## Rules
+
+- **Keep workflows focused**: each workflow should serve one clear purpose. Don't combine unrelated processes.
+- **Role names must match team composition**: roles are resolved to team members. Use names that correspond to the team's actual member names or skills.
+- **Write clear prompts**: each step's prompt should be self-contained enough for the assigned agent to execute without ambiguity. Include expected outputs.
+- **Use `depends_on` for ALL dependencies**: if step B needs output from step A, it MUST list A in `depends_on`. Without this, steps run in parallel.
+- **Use `inputs` for deliverable passing**: when a downstream step needs to reference upstream output, declare it in `inputs` so the system injects the context.
+- **Test incrementally**: start with 2-3 steps and validate before adding complexity.
+- **The `name` field MUST be English kebab-case** (e.g., `content-publishing`, `daily-report`).

package/templates/skills/workflow-building/skill.json

@@ -0,0 +1,19 @@
+{
+  "type": "skill",
+  "name": "workflow-building",
+  "displayName": "Workflow Building",
+  "version": "1.0.0",
+  "description": "Design and create workflow templates — YAML format, DAG patterns, scheduling, parameter systems, and role mapping for multi-step automated processes",
+  "author": "markus",
+  "category": "development",
+  "tags": ["builder", "workflow", "automation", "dag", "template"],
+  "i18n": {
+    "zh-CN": {
+      "displayName": "工作流构建",
+      "description": "设计和创建工作流模板 — YAML 格式、DAG 模式、调度、参数系统和多步骤自动化流程的角色映射"
+    }
+  },
+  "skill": {
+    "skillFile": "SKILL.md"
+  }
+}

package/templates/teams/content-team/team.json

@@ -80,6 +80,7 @@
         "description": "多平台适应、素材复用、抖音口播文案",
         "skills": ["self-evolution"]
       }
-    ]
+    ],
+    "workflows": ["workflows/content-publishing.yaml"]
   }
 }