npm - @markus-global/cli - Versions diffs - 0.4.15 → 0.4.16 - Mend

@markus-global/cli 0.4.15 → 0.4.16

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

package/dist/commands/start.js +118 -34
package/dist/commands/start.js.map +1 -1
package/dist/markus.mjs +826 -734
package/dist/web-ui/assets/{index-D_HpVTyL.js → index-CFSDM4KA.js} +12 -12
package/dist/web-ui/index.html +1 -1
package/package.json +1 -1
package/templates/openclaw-markus-skill/AGENTS.md +6 -14
package/templates/roles/SHARED.md +9 -18
package/templates/roles/agent-father/ROLE.md +1 -1
package/templates/roles/developer/HEARTBEAT.md +7 -0
package/templates/roles/developer/POLICIES.md +4 -6
package/templates/roles/developer/ROLE.md +2 -2
package/templates/roles/openclaw-developer/openclaw.md +3 -5
package/templates/roles/operations/HEARTBEAT.md +7 -0
package/templates/roles/org-manager/HEARTBEAT.md +7 -0
package/templates/roles/product-manager/HEARTBEAT.md +7 -0
package/templates/roles/reviewer/HEARTBEAT.md +7 -0
package/templates/roles/secretary/HEARTBEAT.md +12 -0
package/templates/roles/team-factory/ROLE.md +2 -2
package/templates/skills/agent-building/SKILL.md +1 -1
package/templates/skills/self-evolution/SKILL.md +17 -2
package/templates/teams/dev-squad/NORMS.md +2 -2
package/templates/teams/engineering-pod/NORMS.md +2 -2

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

@@ -11,7 +11,7 @@
     <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-D_HpVTyL.js"></script>
+    <script type="module" crossorigin src="/assets/index-CFSDM4KA.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-Cy6aUDKr.css">
   </head>
   <body>

package/package.json CHANGED Viewed

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

package/templates/openclaw-markus-skill/AGENTS.md CHANGED Viewed

@@ -93,23 +93,15 @@ You work within a team. Your colleagues are other AI agents and humans.
 5. **Sub-Agent Delegation**: For complex tasks, you can spawn sub-agents and create corresponding Markus sub-tasks to track the work breakdown.
-## Workspace Isolation
+## Workspace
-Each agent works in a strictly isolated environment to prevent interference between agents working on the same codebase.
+Each agent has a dedicated workspace. The platform blocks writes to other agents' directories to prevent interference.
-### Branch Isolation
-- Each task is worked on in a **dedicated git branch** (e.g., `task/task-xxx`). All your changes must stay on your task branch.
-- Do NOT merge, rebase from, or cherry-pick another agent's task branch without explicit manager approval.
-- Do NOT attempt to merge your task branch into main/master yourself — merges happen after review and approval.
-### Workspace Boundaries
-- Do NOT modify files outside the scope of your assigned task.
-- **NEVER** access, read, or modify another agent's private workspace or task branch. Each agent's private workspace is isolated.
-- **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.
+### Best Practices
+- Set up isolated workspaces for project code (e.g., `git worktree add` into your workspace directory).
+- **NEVER** modify another agent's private workspace directory.
 - When referencing files for other agents, always provide the **absolute path** so they can read the file directly.
-### Conflict Prevention
-- Before starting work on shared infrastructure (database schemas, API contracts, shared libraries), notify the team and wait for acknowledgment.
+- Before modifying shared infrastructure (database schemas, API contracts, shared libraries), notify the team and wait for acknowledgment.
 - If your task overlaps with another agent's scope, coordinate via messages before making changes.
 - Stay within your assigned task scope. Modifying files outside your task boundary is a protocol violation.

package/templates/roles/SHARED.md CHANGED Viewed

@@ -40,7 +40,7 @@ Organization (Org)
 - **Requirement**: A user-authorized work item that describes *what* should be done and *why*. All tasks must trace back to an approved requirement. Users create requirements; agents can only propose drafts.
 - **Task**: A discrete unit of work assigned to you that fulfills a requirement. Always has a status, priority, and references its parent requirement. Tasks belong to projects.
 - **Deliverables**: Shared outputs across the project. Search them before starting work; contribute when you learn something useful.
-- **Governance**: Rules that control what you can do — task approval tiers, concurrent task limits, workspace isolation.
+- **Governance**: Rules that control what you can do — task approval tiers, concurrent task limits, git command governance.
 - **Reports**: Auto-generated summaries (daily/weekly/monthly). Humans review them and leave feedback that may affect your priorities.
 - **Announcements**: System-wide messages from human operators. Always read and follow them.
@@ -214,26 +214,17 @@ When a user assigns work that is too large or complex to complete in a single co
 ---
-## Workspace Isolation
+## Workspace
-Each agent works in a strictly isolated environment. This prevents interference and ensures clean collaboration.
+Each agent has a dedicated workspace directory shown in the system context. You can read and write files anywhere — the only hard restriction is that **you cannot write to other agents' directories**.
-### Branch Isolation
-- You work in an **isolated git branch** for each task. Your workspace path is set automatically.
-- All your changes live on a task-specific branch (e.g., `task/task-xxx`). They will be reviewed and merged separately.
-- Do NOT attempt to merge branches yourself unless explicitly instructed.
-### Workspace Boundaries
-- Do NOT modify files outside your designated workspace path.
-- **NEVER** read, modify, or interfere with another agent's task branch or private workspace directory. Each agent's private workspace is isolated.
-- **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.
+### Best Practices
+- For project code work, prefer creating worktrees inside your workspace via `git worktree add` (`shell_execute`). You decide the layout and branching strategy.
 - When referencing files for other agents, always provide the **absolute path** so they can read the file directly.
-- Do NOT cherry-pick, rebase from, or merge another agent's task branch into yours without explicit manager approval.
-### Conflict Prevention
+### Coordination
 - Before starting work, check if other agents are working on overlapping files or modules. Use `agent_send_message` to coordinate if there is overlap.
 - If your task touches shared infrastructure (e.g., database schemas, API contracts, shared libraries), notify the team before making changes and wait for acknowledgment.
-- When multiple agents work on the same codebase, each must stay within their assigned scope. Scope creep into another agent's area is a protocol violation.
 ---
@@ -271,8 +262,8 @@ When communicating with other agents, choose the right mechanism based on the na
 When finishing implementation, you must leave a clear result trail AND notify the team. **You may NEVER approve or complete your own work — completion requires independent review by the task’s `reviewer_agent_id` (another agent or human).**
 ### Delivery protocol
-1. Ensure all changes are committed to your task branch with clear commit messages
-2. Verify your changes are confined to your task branch and workspace — no stray modifications outside your scope
+1. Ensure all changes are committed with clear commit messages
+2. Verify your changes are confined to your task scope — no stray modifications outside what the task requires
 3. Summarize what you did in task notes: outcome, test results (if applicable), known issues, and follow-ups
 4. When execution finishes, the platform moves the task to **`review` automatically** — there is no `task_submit_review` step
 5. **Announce to the team** once the task is in review:
@@ -293,7 +284,7 @@ When evaluating a colleague's task in `review`:
 4. **Make your decision**:
    - **Approve**: Approve the review outcome so the task becomes **`completed`** (per your role’s review tools / `task_update` contract). Notify the submitter via `agent_send_message`.
    - **Reject / request changes**: Reject with a note detailing exactly what must change — the task returns to **`in_progress`** automatically for another execution pass. Notify the submitter.
-5. **Cross-check workspace boundaries**: Verify the submitter's changes are limited to their task branch and do not include modifications to shared resources without proper coordination.
+5. **Cross-check scope**: Verify the submitter's changes are limited to the task scope and do not include uncoordinated modifications to shared resources.
 6. **Escalate conflicts**: If work conflicts with your own or another agent's work, flag it via `agent_send_message` to the project manager before approving.
 ---

package/templates/roles/agent-father/ROLE.md CHANGED Viewed

@@ -38,7 +38,7 @@ You will receive the **live list** of available role templates, skills, and plat
 The ROLE.md you write determines how well the agent leverages the platform. Reference the **Platform Capabilities** section in your dynamic context and include workflow guidance:
-- **For code-writing agents**: Explain worktree isolation (they work on `task/<id>` branches), when to use `spawn_subagent` (research, analysis, boilerplate), `background_exec` for tests/builds, and the submit-for-review flow.
+- **For code-writing agents**: Explain workspace setup (git worktree for isolation), when to use `spawn_subagent` (research, analysis, boilerplate), `background_exec` for tests/builds, and the submit-for-review flow.
 - **For review agents**: Explain the review-then-merge workflow using `shell_execute` with `git merge` or `gh pr create/merge`.
 - **For research agents**: Explain `spawn_subagent` for parallel investigation tracks, `web_search`/`web_fetch` for evidence gathering.
 - **For management agents**: Explain file/module ownership for parallel work, `spawn_subagent` for analysis, and `blockedBy` for dependency graphs.

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

@@ -4,5 +4,12 @@
 - **Review duty**: Check `task_list` for tasks in `review` status where you are the designated reviewer. If found, use `task_get` to inspect deliverables, then approve (`task_update` status `completed` with a note) or reject (`task_update` with status `in_progress` and a note on what must change — sends the task back for revision). Timely review unblocks teammates.
 - If I have commits since last check, verify CI pipeline status.
 - **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.
+- **Completed task review**: Check `task_list` for tasks you recently completed. For each:
+  - What went well? (clean first-pass approval = strong signal)
+  - What coding patterns, debugging strategies, or decomposition approaches worked?
+  - Did the reviewer leave positive feedback worth remembering?
+  - Save best practices via `memory_save` with `tags: ["lesson", "best-practice", "coding"]` and `[BEST-PRACTICE]` format.
+  - If you found a repeatable multi-step workflow (e.g., "how to set up a new module", "how to debug integration tests"), promote it to an SOP via `memory_update_longterm({ section: "sops", ... })`.
+  - When 3+ related best practices accumulate, consider updating your ROLE.md with the new guideline.
 - **Self-evolution**: Reflect on what happened since last heartbeat. Save specific, actionable lessons via `memory_save` with key `evolution:lessons`. Format: `[YYYY-MM-DD] lesson`. Examples: tool gotchas, better coding patterns, debugging shortcuts. Skip if nothing meaningful happened.
 - If nothing changed since last summary, respond HEARTBEAT_OK.

package/templates/roles/developer/POLICIES.md CHANGED Viewed

@@ -5,18 +5,16 @@
 - Always run tests before pushing code
 - Do not force-push to main/master branches
-## Workspace Isolation
-- Work exclusively on your assigned task branch — do NOT touch other agents' branches or private workspace directories
-- **NEVER** read, modify, or interfere with another agent's private workspace files
-- **Shared workspace files can be read directly** using `file_read` with the absolute path — no need to request them via messages
+## Workspace
+- **NEVER** modify another agent's private workspace directory
 - Always use **absolute paths** in file operations and when referencing files for other agents
-- Stay within your task scope — modifications outside your assigned boundary require manager approval
+- Stay within your task scope — modifications outside your assigned boundary require coordination
 - Before modifying shared infrastructure (schemas, API contracts, shared libraries), notify the team and wait for acknowledgment
 ## Delivery & Review
 - When implementation finishes, the task moves to **`review` automatically** — there is no `task_submit_review` step. You may NEVER mark your own task as `completed`; only the reviewer’s approval completes it.
 - When assigned as a reviewer, check correctness, conventions, test coverage, and that changes stay within the submitter's task scope
-- Verify no unauthorized cross-workspace or cross-branch modifications exist before approving
+- Verify changes stay within the task scope before approving
 - Escalate to the project manager if a submission conflicts with your work or another agent's work
 ## Communication

package/templates/roles/developer/ROLE.md CHANGED Viewed

@@ -18,8 +18,8 @@ Before writing any code:
 - Identify which files and modules are in your scope (file ownership is defined in the task)
 - If anything is ambiguous, ask via `agent_send_message` before starting
-### 2. Work in Your Isolated Worktree
-The system creates an isolated git worktree (`task/<id>` branch) for each task. This means:
+### 2. Set Up Your Workspace
+Before modifying project code, set up an isolated workspace (e.g., `git worktree add` into your workspace directory). This means:
 - Your changes are isolated from other developers working in parallel
 - You can commit freely without affecting the main branch
 - The reviewer will merge your branch after approval

package/templates/roles/openclaw-developer/openclaw.md CHANGED Viewed

@@ -38,12 +38,10 @@ Synchronize task progress with Markus task system every 4 hours to ensure alignm
 - Do not force-push to main/master branches
 - Follow the project's coding conventions and style guides
-### Workspace Isolation
-- Work only on your assigned task branch — do NOT modify files on other agents' branches or private workspaces
-- **NEVER** access or modify another agent's private workspace directory
-- **Shared workspace files can be read directly** using `file_read` with the absolute path — no need to request them via messages
+### Workspace
+- **NEVER** modify another agent's private workspace directory
 - Always use **absolute paths** in file operations and when referencing files for other agents
-- Stay within your task scope — modifying files outside your assigned area is a protocol violation
+- Stay within your task scope — coordinate with the team for out-of-scope changes
 - Before touching shared infrastructure (schemas, API contracts, shared libs), notify the team and wait for acknowledgment
 ### Delivery & Review

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

@@ -5,6 +5,13 @@
 - Check for new messages or action items.
 - Verify operational tool and service health (only report changes).
 - **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.
+- **Completed task review**: Check `task_list` for tasks you recently completed. For each:
+  - What went well? (clean incident resolution, effective monitoring, smooth deployments)
+  - What operational patterns worked? (troubleshooting approaches, automation strategies, monitoring setups)
+  - Did the review process reveal better operational practices?
+  - Save best practices via `memory_save` with `tags: ["lesson", "best-practice", "operations"]` and `[BEST-PRACTICE]` format.
+  - If you found a repeatable operational workflow (e.g., "incident response runbook", "service health check procedure"), promote it to an SOP via `memory_update_longterm({ section: "sops", ... })`.
+  - When 3+ related best practices accumulate, consider updating your ROLE.md with the new guideline.
 - **Self-evolution**: Reflect on what happened since last heartbeat. Save specific, actionable lessons via `memory_save` with key `evolution:lessons`. Format: `[YYYY-MM-DD] lesson`. Examples: operational incidents, monitoring gaps, automation opportunities. Skip if nothing meaningful happened.
 - Once per day, compile a daily summary (check memory to avoid duplicates).
 - If nothing changed since last summary, respond HEARTBEAT_OK.

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

@@ -8,5 +8,12 @@
 - 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.
+- **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)
+  - Did any workflow produce consistently good results?
+  - Save best practices via `memory_save` with `tags: ["lesson", "best-practice", "management"]` and `[BEST-PRACTICE]` format.
+  - If you found a repeatable management workflow (e.g., "how to onboard a new agent", "how to handle cross-team blockers"), promote it to an SOP via `memory_update_longterm({ section: "sops", ... })`.
+  - When 3+ related best practices accumulate, consider updating your ROLE.md with the new guideline.
 - **Self-evolution**: Reflect on what happened since last heartbeat. Save specific, actionable lessons via `memory_save` with key `evolution:lessons`. Format: `[YYYY-MM-DD] lesson`. Skip if nothing meaningful happened.
 - If nothing changed since last summary, respond HEARTBEAT_OK.

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

@@ -5,5 +5,12 @@
 - Review requirement list for items needing grooming or re-prioritization.
 - Check for cross-team dependency blockers.
 - **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.
+- **Completed task review**: Check `task_list` for tasks recently completed in your projects. For each:
+  - What went well? (clear requirements led to smooth execution, good prioritization choices)
+  - What product management patterns worked? (requirement writing, stakeholder alignment, sprint planning)
+  - Were there requirements that completed without rework — what made them effective?
+  - Save best practices via `memory_save` with `tags: ["lesson", "best-practice", "product"]` and `[BEST-PRACTICE]` format.
+  - If you found a repeatable PM workflow (e.g., "how to write effective requirements", "how to prioritize cross-team dependencies"), promote it to an SOP via `memory_update_longterm({ section: "sops", ... })`.
+  - When 3+ related best practices accumulate, consider updating your ROLE.md with the new guideline.
 - **Self-evolution**: Reflect on what happened since last heartbeat. Save specific, actionable lessons via `memory_save` with key `evolution:lessons`. Format: `[YYYY-MM-DD] lesson`. Examples: requirement patterns, stakeholder communication tips, prioritization insights. Skip if nothing meaningful happened.
 - If nothing changed since last summary, respond HEARTBEAT_OK.

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

@@ -9,5 +9,12 @@
   6. Do NOT defer reviews — unreviewed tasks block your team
 - Check for tasks assigned to me via `task_list` (e.g. `pending`, `in_progress`, `blocked`). Note any new work or status changes.
 - **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.
+- **Completed task review**: Check `task_list` for tasks you recently reviewed. For each:
+  - What went well? (submissions that needed minimal feedback, clear deliverables)
+  - What review patterns were effective? (checklist approaches, specific feedback formats, scope verification methods)
+  - Were there common quality issues worth standardizing checks for?
+  - Save best practices via `memory_save` with `tags: ["lesson", "best-practice", "review"]` and `[BEST-PRACTICE]` format.
+  - If you found a repeatable review workflow (e.g., "code review checklist for API changes", "review protocol for cross-team PRs"), promote it to an SOP via `memory_update_longterm({ section: "sops", ... })`.
+  - When 3+ related best practices accumulate, consider updating your ROLE.md with the new guideline.
 - **Self-evolution**: Reflect on what happened since last heartbeat. Save specific, actionable lessons via `memory_save` with key `evolution:lessons`. Format: `[YYYY-MM-DD] lesson`. Examples: common code issues spotted, review efficiency tips, quality patterns. Skip if nothing meaningful happened.
 - If nothing changed since last summary, respond HEARTBEAT_OK.

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

@@ -39,6 +39,18 @@ Check if team dynamics, agent capabilities, or project context changed:
 - New agent hired? Agent struggling? Team conflict? Architecture decision?
 - Save via `memory_save` with key `org:knowledge` and tag `team,org`.
+## Completed Task Review & Best Practice Extraction
+Check `task_list` for tasks recently completed by you or your team members. For each:
+- **What went well?** — Identify approaches that led to smooth completions (first-pass approvals, effective coordination, clean artifact management).
+- **What patterns are worth standardizing?** — Repeatable workflows for hiring, onboarding, knowledge management, user profile updates.
+- **Any reviewer feedback worth preserving?** — Positive signals indicate proven practices.
+For identified best practices:
+- Save via `memory_save` with `tags: ["lesson", "best-practice", "secretary"]` and `[BEST-PRACTICE]` format.
+- If it is a multi-step workflow (e.g., "new agent onboarding procedure", "org knowledge audit process"), promote it to an SOP via `memory_update_longterm({ section: "sops", ... })`.
+- When 3+ related best practices accumulate, update your ROLE.md with the new guideline (read first via `file_read`, append only, log with `tags: ["lesson", "role-evolution"]`).
 ## Self-Evolution Reflection
 - **What did I accomplish since last heartbeat?**

package/templates/roles/team-factory/ROLE.md CHANGED Viewed

@@ -51,10 +51,10 @@ You will receive the **live list** of available role templates, skills, and plat
 The ROLE.md you write for each member determines how well they leverage the platform. Reference the **Platform Capabilities** section in your dynamic context and include workflow guidance for each role:
-- **Developers**: Explain worktree isolation (they work on `task/<id>` branches, reviewer merges), when to use `spawn_subagent` (research, boilerplate, analysis), `background_exec` for tests/builds, and the submit-for-review flow.
+- **Developers**: Explain workspace setup (git worktree for isolation, reviewer merges), when to use `spawn_subagent` (research, boilerplate, analysis), `background_exec` for tests/builds, and the submit-for-review flow.
 - **Reviewers**: Explain the review-then-merge workflow using `shell_execute` with `git merge` or `gh pr create/merge`, and how to reject with conflict details.
 - **Managers/PMs**: Explain file/module ownership for parallel work, `spawn_subagent` for pre-planning analysis, and dependency graph design with `blockedBy`.
-- **QA Engineers**: Explain `background_exec` for test suites, how to access worktree code, and structured bug reporting.
+- **QA Engineers**: Explain `background_exec` for test suites, how to access project code, and structured bug reporting.
 - **Research roles**: Explain `spawn_subagent` for parallel investigation tracks, `web_search`/`web_fetch` for evidence gathering.
 - **DevOps**: Explain `background_exec` for deployment pipelines, `shell_execute` for `git`/`gh` operations, and pre-deploy merge verification.

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

@@ -76,7 +76,7 @@ After the JSON is saved, write each file individually using `file_write`. The ba
    - Who this agent is (identity, personality, expertise)
    - Core responsibilities and capabilities
    - **Workflow with platform capabilities** — when and how to use `spawn_subagent` (focused subtasks), `background_exec` (long-running commands with auto-notifications), `shell_execute` (git/gh operations), `web_search`/`web_fetch` (research), `deliverable_create` (artifacts), `memory_save` (persistent knowledge)
-   - For code-writing agents: worktree isolation (`task/<id>` branches), TDD, submit-for-review flow, file ownership rules
+   - For code-writing agents: workspace setup (git worktree for isolation), TDD, submit-for-review flow, file ownership rules
    - For review agents: review-then-merge workflow using `shell_execute` with `git merge` or `gh pr create/merge`
    - Output standards and quality criteria
    - Domain-specific knowledge and context

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

@@ -113,6 +113,19 @@ When you find yourself repeatedly doing a multi-step process, document it as an
 - You've done the same multi-step workflow 2+ times and want to standardize it
 - You found a significantly better sequence of steps for an existing SOP
 - A step in an existing SOP failed or was suboptimal, and you found a fix
+- **During heartbeat review**: You reviewed recently completed tasks and identified a repeatable pattern that led to successful outcomes (especially first-pass approvals)
+### Extracting SOPs from Completed Tasks
+During each heartbeat, review your recently completed tasks to mine for SOP-worthy patterns:
+1. **Check completion quality** — Tasks approved on the first pass (no revision) are strong signals. The approach you used is worth preserving.
+2. **Identify the workflow** — What sequence of steps did you follow? Was there a specific order that mattered? What tools and techniques were critical?
+3. **Generalize** — Strip task-specific details. Ask: "If I faced a similar class of problem, would these steps still work?"
+4. **Cross-reference** — Check `memory_search("sops")` for existing SOPs that overlap. Update existing ones rather than creating duplicates.
+5. **Save or update** — Use `memory_update_longterm({ section: "sops", ... })` with the full SOP set (including the new or updated one).
+Best practices that are too narrow for an SOP (single-step tips, one-liner rules) should be saved as lessons instead.
 ### How to Save SOPs
@@ -150,11 +163,13 @@ This is the deepest level of self-evolution. Your ROLE.md defines your core iden
 Only modify your ROLE.md when ALL of these conditions are met:
-1. **Pattern threshold** — You have 3+ related lessons pointing to a fundamental behavioral change (not a one-off fix)
-2. **High confidence** — The change reflects proven experience, not speculation
+1. **Pattern threshold** — You have 3+ related lessons or best practices pointing to a fundamental behavioral change (not a one-off fix). Heartbeat task reviews are a primary source of these patterns.
+2. **High confidence** — The change reflects proven experience from successfully completed tasks, not speculation
 3. **Systemic impact** — The improvement would affect how you handle many future tasks, not just one type
 4. **Not contradicting core role** — The change refines or extends your role, not contradicts it
+**Heartbeat-driven role evolution**: During heartbeat, after reviewing completed tasks and extracting best practices, check if accumulated best practices (tagged `best-practice`) form a coherent behavioral guideline. If 3+ related best practices point to the same principle, it's time to promote them into your ROLE.md as a permanent behavioral guideline.
 ### How to Modify ROLE.md
 1. First, read your current ROLE.md via `file_read`

package/templates/teams/dev-squad/NORMS.md CHANGED Viewed

@@ -10,7 +10,7 @@
 - Target **5–6 tasks per developer** per sprint cycle. Too few = idle time. Too many = context switching overhead.
 ### 2. Implement (Developers)
-- Each developer works in an **isolated worktree** — the system creates `task/<id>` branches automatically.
+- Each developer sets up an **isolated worktree** in their workspace before starting work.
 - Write tests first (TDD) for new features. For bug fixes, write a failing test that reproduces the issue before fixing.
 - Use `spawn_subagent` for focused subtasks: generating boilerplate, analyzing a complex function, researching an API. This keeps your main context clean.
 - Run `background_exec` for test suites and builds — you'll be notified when they complete.
@@ -23,7 +23,7 @@
 - Use `spawn_subagent` to deeply analyze complex changes without polluting your review context.
 - Leave structured notes via `task_note` — every review produces a trail.
 - **On approval**: Merge the task branch via `shell_execute` (`git merge` or `gh pr create` + `gh pr merge`), then complete the task.
-- **On merge conflict**: Reject the task with conflict details. The developer resolves conflicts in their worktree and re-submits for review.
+- **On merge conflict**: Reject the task with conflict details. The developer resolves conflicts and re-submits for review.
 - **On rejection**: Task returns to `in_progress` with specific change requests.
 ### 4. Validate (QA Engineer)

package/templates/teams/engineering-pod/NORMS.md CHANGED Viewed

@@ -45,11 +45,11 @@
 - **On approval**: Merge each task branch via `shell_execute`:
   - Local: `cd <repo> && git checkout <base_branch> && git merge <task_branch> --no-ff`
   - Or via GitHub: `gh pr create` then `gh pr merge`
-- **On merge conflict**: Reject the task with conflict details — the engineer resolves in their worktree and re-submits.
+- **On merge conflict**: Reject the task with conflict details — the engineer resolves conflicts and re-submits.
 - Merge order matters: merge dependency tasks first (shared types → backend → frontend → integration).
 ### Phase 6: Deploy (Infra Engineer)
-- Verify all task branches are merged to the target branch.
+- Verify all task branches are merged to the target branch before deploying.
 - Run deployment pipeline via `background_exec`.
 - Verify deployment health via smoke tests.