@modus-ai/modus 0.1.1 → 0.1.2

package/templates/agents/modus-harness-06-review.md

@@ -0,0 +1,16 @@
+---
+name: modus-harness-06-review
+description: Use this agent when the Harness orchestrator needs comprehensive code review after all audit reports are ready (Gate B passed). Reviews all artifacts (01-analysis.md through 05-security-report.md) plus actual code changes, grades issues as P1/P2/P3, and produces cr-report.md. If P1/P2 issues exist, orchestrator triggers Loop 2 re-entry into SubAgent 02.
+agentMode: agentic
+tools: Read, Write, Glob
+enabledAutoRun: true
+enabled: true
+---
+
+读取并严格遵循 `.codebuddy/skills/modus-harness-06-review/SKILL.md` 中的执行规范。
+
+输入依赖：全部产出物（01-analysis.md 至 05-security-report.md）的 HANDOFF 块 + 代码变更。
+
+产出物路径：`modus/plans/active/{story-id}/cr-report.md`。
+
+产出物头部 HANDOFF 块中的 `issues` 字段列出所有 P1/P2 问题，`gate_status: passed` 表示无 P1/P2 可进入 Gate C。

package/templates/agents/modus-harness-07-deploy.md

@@ -0,0 +1,16 @@
+---
+name: modus-harness-07-deploy
+description: Use this agent when the Harness orchestrator needs to verify deployment after Gate C passes (cr-report has no P1/P2 issues). Monitors CI/CD pipeline status, validates service health across environments (dev→uat→pre→prd), executes smoke tests on P0 interfaces, monitors ERROR log volume for 30 minutes post-deployment, and produces 07-deploy-status.md. prd environment requires manual confirmation.
+agentMode: agentic
+tools: Read, Write, Glob, Bash, WebFetch
+enabledAutoRun: false
+enabled: true
+---
+
+读取并严格遵循 `.codebuddy/skills/modus-harness-07-deploy/SKILL.md` 中的执行规范。
+
+输入依赖：`cr-report.md`（HANDOFF.gate_status = passed）+ `02-sprint-contract.md`。
+
+产出物路径：`modus/plans/active/{story-id}/07-deploy-status.md`。
+
+**注意：** `enabledAutoRun: false` — prd 环境部署操作需等待人工确认后方可继续。产出物头部必须包含 HANDOFF 块。

package/templates/commands/modus.md

@@ -0,0 +1,25 @@
+# /modus
+
+Modus — Business-grounded AI coding accelerator.
+
+## Available Commands
+
+| Command | Description |
+|---|---|
+| `/modus:init` | Scan codebase, classify business domains, generate domain Skill files |
+| `/modus:vibe` | Context-aware vibe coding with business Skill backing |
+| `/modus:plan` | Plan mode with Skill-backed business context |
+| `/modus:spec` | OpenSpec-style spec-driven development |
+| `/modus:harness` | Full dual-loop multi-agent Harness (analyze → dev → test → review → deploy) |
+
+## Quick Start
+
+1. Run `/modus:init` once to scan your project and build business Skills
+2. Use `/modus:vibe` for day-to-day coding with project context
+3. Use `/modus:harness` for full-cycle feature delivery from a TAPD Story URL
+
+## Tips
+
+- Business Skill files live in `.codebuddy/skills/modus-biz-*/SKILL.md`
+- Re-run `/modus:init` any time your domain model changes
+- All commands fall back gracefully if business Skills are missing

package/templates/hooks/post-tool-use-lint.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""
+Modus PostToolUse Lint Hook
+After a file is written or edited, emits a lightweight lint reminder for
+Java and TypeScript files so the AI agent can self-correct common issues.
+"""
+import json
+import os
+import sys
+
+JAVA_REMINDERS = [
+    "确认事务方法不在同类中内部调用（应通过 AopContext.currentProxy() 或拆分到独立 Bean）",
+    "确认 tenantId 来自 UserContext，而非 request 参数",
+    "确认金额字段使用 Long（单位：分），避免浮点精度问题",
+    "确认 Mapper 接口位于 dao 包下",
+    "确认枚举值使用 name() 而非 ordinal() 进行持久化",
+]
+
+TS_REMINDERS = [
+    "确认异步函数有 await/catch 异常处理",
+    "确认 React 组件使用函数式写法，避免 class 组件",
+    "确认 API 调用有 loading 状态和错误提示",
+]
+
+EXT_MAP: dict[str, list[str]] = {
+    ".java": JAVA_REMINDERS,
+    ".ts": TS_REMINDERS,
+    ".tsx": TS_REMINDERS,
+}
+
+
+def get_reminders(file_path: str) -> list[str]:
+    _, ext = os.path.splitext(file_path.lower())
+    return EXT_MAP.get(ext, [])
+
+
+def main() -> int:
+    input_data = json.loads(sys.stdin.read())
+
+    tool_name = input_data.get("tool_name", "")
+    # Support both CLI-style and IDE-style tool names
+    if tool_name not in ("Write", "Edit", "write_to_file", "replace_in_file"):
+        print(json.dumps({"continue": True}))
+        return 0
+
+    tool_input = input_data.get("tool_input", {})
+    file_path = (
+        tool_input.get("path")
+        or tool_input.get("filePath")
+        or tool_input.get("file_path")
+        or ""
+    )
+
+    reminders = get_reminders(file_path)
+    if not reminders:
+        print(json.dumps({"continue": True}))
+        return 0
+
+    lang = os.path.splitext(file_path)[1].lstrip(".")
+    reminder_text = (
+        f"[Modus Lint 提示 — {file_path}]\n"
+        + "\n".join(f"- {r}" for r in reminders)
+    )
+
+    output = {
+        "continue": True,
+        "hookSpecificOutput": {
+            "hookEventName": "PostToolUse",
+            "additionalContext": reminder_text,
+        },
+    }
+
+    print(json.dumps(output, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/templates/hooks/pre-compact-save.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""
+Modus PreCompact Hook
+Before context is compacted (auto or manual), saves the current state of
+active Harness plans and appends a summary to the compaction instructions
+so critical in-progress decisions are preserved.
+"""
+import json
+import os
+import shutil
+import sys
+from datetime import datetime, timezone
+
+TRACKED_ARTIFACTS = [
+    "01-analysis.md",
+    "02-sprint-contract.md",
+    "cr-report.md",
+    ".modus-state.yaml",
+]
+
+
+def snapshot_active_plans(project_dir: str) -> list[str]:
+    """Copies active plan artifacts to a timestamped snapshot dir. Returns list of saved paths."""
+    active_dir = os.path.join(project_dir, "modus", "plans", "active")
+    if not os.path.isdir(active_dir):
+        return []
+
+    ts = datetime.now(tz=timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    snapshot_base = os.path.join(project_dir, "modus", ".compact-snapshots", ts)
+    saved: list[str] = []
+
+    for story_id in os.listdir(active_dir):
+        plan_dir = os.path.join(active_dir, story_id)
+        if not os.path.isdir(plan_dir):
+            continue
+        for artifact in TRACKED_ARTIFACTS:
+            src = os.path.join(plan_dir, artifact)
+            if os.path.exists(src):
+                dst_dir = os.path.join(snapshot_base, story_id)
+                os.makedirs(dst_dir, exist_ok=True)
+                shutil.copy2(src, os.path.join(dst_dir, artifact))
+                saved.append(f"{story_id}/{artifact}")
+
+    return saved
+
+
+def build_context_hint(project_dir: str) -> str:
+    """Reads HANDOFF blocks from active plans to give the compactor key context."""
+    active_dir = os.path.join(project_dir, "modus", "plans", "active")
+    hints: list[str] = []
+
+    if not os.path.isdir(active_dir):
+        return ""
+
+    for story_id in os.listdir(active_dir):
+        plan_dir = os.path.join(active_dir, story_id)
+        if not os.path.isdir(plan_dir):
+            continue
+
+        # Read .modus-state.yaml for current phase
+        state_path = os.path.join(plan_dir, ".modus-state.yaml")
+        state_snippet = ""
+        if os.path.exists(state_path):
+            try:
+                with open(state_path, encoding="utf-8") as f:
+                    state_snippet = f.read(500)
+            except OSError:
+                pass
+
+        hints.append(
+            f"[Story {story_id}]\n{state_snippet.strip() if state_snippet else '（状态未知）'}"
+        )
+
+    if not hints:
+        return ""
+
+    return (
+        "=== Modus 进行中任务（压缩时必须保留）===\n\n"
+        + "\n\n".join(hints)
+        + "\n\n重要：压缩后必须能继续执行上述 Harness 任务的下一步骤。"
+    )
+
+
+def main() -> int:
+    input_data = json.loads(sys.stdin.read())
+
+    project_dir = os.environ.get("CODEBUDDY_PROJECT_DIR") or os.environ.get(
+        "CLAUDE_PROJECT_DIR", input_data.get("cwd", "")
+    )
+
+    saved = snapshot_active_plans(project_dir)
+    hint = build_context_hint(project_dir)
+
+    if not hint and not saved:
+        print(json.dumps({"continue": True}))
+        return 0
+
+    lines = []
+    if saved:
+        lines.append(f"已备份活跃计划快照（{len(saved)} 个文件）到 modus/.compact-snapshots/")
+    if hint:
+        lines.append(hint)
+
+    output = {
+        "continue": True,
+        "hookSpecificOutput": {
+            "hookEventName": "PreCompact",
+            "additionalContext": "\n\n".join(lines),
+        },
+    }
+
+    print(json.dumps(output, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/templates/hooks/pre-tool-use-safety.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""
+Modus PreToolUse Safety Hook
+Intercepts Bash commands and blocks dangerous operations that could cause
+irreversible damage to the project or infrastructure.
+"""
+import json
+import re
+import sys
+from typing import Optional
+
+DENY_PATTERNS: list[tuple[str, str]] = [
+    (r"rm\s+-rf\s+/", "禁止删除根目录"),
+    (r"rm\s+-rf\s+~", "禁止删除家目录"),
+    (r"git\s+push\s+.*--force\s+.*(?:main|master|release)", "禁止强制推送到主干分支"),
+    (r"git\s+push\s+(?:origin\s+)?(?:main|master|release)\s+--force", "禁止强制推送到主干分支"),
+    (r"dd\s+if=/dev/zero", "禁止 dd 覆写设备"),
+    (r"mkfs\.", "禁止格式化分区"),
+    (r">\s*/dev/sd[a-z]", "禁止直接写入块设备"),
+    (r"chmod\s+-R\s+777\s+/", "禁止对根目录递归授权 777"),
+    (r"DROP\s+DATABASE", "禁止 DROP DATABASE（请在数据库客户端手动执行）"),
+    (r"TRUNCATE\s+TABLE\s+\w+\s*;?\s*$", "高危 TRUNCATE 操作，请确认后手动执行"),
+]
+
+ASK_PATTERNS: list[tuple[str, str]] = [
+    (r"git\s+push\s+.*--force", "检测到 git force push，请确认目标分支安全"),
+    (r"git\s+reset\s+--hard", "检测到 git reset --hard，将丢失未提交的变更"),
+    (r"git\s+clean\s+-fd", "检测到 git clean -fd，将删除未跟踪文件"),
+    (r"npm\s+publish", "检测到 npm publish，将发布包到 registry"),
+    (r"kubectl\s+delete", "检测到 kubectl delete，将删除 K8s 资源"),
+]
+
+
+def check_command(command: str) -> tuple[str, Optional[str]]:
+    """Returns (decision, reason): decision is 'allow' | 'deny' | 'ask'."""
+    for pattern, reason in DENY_PATTERNS:
+        if re.search(pattern, command, re.IGNORECASE):
+            return "deny", reason
+    for pattern, reason in ASK_PATTERNS:
+        if re.search(pattern, command, re.IGNORECASE):
+            return "ask", reason
+    return "allow", None
+
+
+def main() -> int:
+    input_data = json.loads(sys.stdin.read())
+
+    tool_name = input_data.get("tool_name", "")
+    # Support both CLI-style (Bash) and IDE-style (execute_command) tool names
+    if tool_name not in ("Bash", "execute_command"):
+        print(json.dumps({"continue": True}))
+        return 0
+
+    command = input_data.get("tool_input", {}).get("command", "")
+    if not command:
+        print(json.dumps({"continue": True}))
+        return 0
+
+    decision, reason = check_command(command)
+
+    output: dict = {
+        "continue": decision != "deny",
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": decision,
+        },
+    }
+
+    if reason:
+        output["hookSpecificOutput"]["permissionDecisionReason"] = reason
+
+    if decision == "deny":
+        output["stopReason"] = f"[Modus 安全拦截] {reason}"
+
+    print(json.dumps(output, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/templates/hooks/session-start.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""
+Modus SessionStart Hook
+Injects project context (knowledge-catalog + active plans + constitution) into
+the session so every conversation starts with business knowledge pre-loaded.
+"""
+import json
+import os
+import sys
+
+
+def read_file_safe(path: str, max_bytes: int = 8000) -> str:
+    try:
+        with open(path, encoding="utf-8") as f:
+            return f.read(max_bytes)
+    except OSError:
+        return ""
+
+
+def main() -> int:
+    input_data = json.loads(sys.stdin.read())
+    project_dir = os.environ.get("CODEBUDDY_PROJECT_DIR") or os.environ.get(
+        "CLAUDE_PROJECT_DIR", input_data.get("cwd", "")
+    )
+
+    context_parts: list[str] = []
+
+    # 1. knowledge-catalog — Level 1 index (~200 tokens)
+    catalog_path = os.path.join(project_dir, "modus", "knowledge-catalog.md")
+    catalog = read_file_safe(catalog_path, 3000)
+    if catalog:
+        context_parts.append(f"[Modus 知识目录]\n{catalog}")
+
+    # 2. constitution from config.yaml
+    config_path = os.path.join(project_dir, "modus", "config.yaml")
+    config_raw = read_file_safe(config_path, 2000)
+    if config_raw:
+        # Extract only the constitution section to keep tokens low
+        in_constitution = False
+        constitution_lines: list[str] = []
+        for line in config_raw.splitlines():
+            if line.strip().startswith("constitution:"):
+                in_constitution = True
+            if in_constitution:
+                constitution_lines.append(line)
+                # Stop at the next top-level key (non-indented, not constitution)
+                if constitution_lines and len(constitution_lines) > 1 and line and not line[0].isspace() and not line.strip().startswith("constitution"):
+                    constitution_lines.pop()
+                    break
+        if constitution_lines:
+            context_parts.append(f"[项目宪法 (constitution)]\n" + "\n".join(constitution_lines))
+
+    # 3. Active Harness plans — list story IDs in progress
+    active_dir = os.path.join(project_dir, "modus", "plans", "active")
+    if os.path.isdir(active_dir):
+        active_stories = [
+            d for d in os.listdir(active_dir)
+            if os.path.isdir(os.path.join(active_dir, d))
+        ]
+        if active_stories:
+            context_parts.append(
+                "[进行中的 Harness 任务]\n" + "\n".join(f"- {s}" for s in active_stories)
+            )
+
+    if not context_parts:
+        output = {"continue": True}
+    else:
+        additional_context = (
+            "=== Modus 项目上下文（自动注入）===\n\n"
+            + "\n\n".join(context_parts)
+            + "\n\n提示：使用 /modus:vibe、/modus:plan、/modus:spec 或 /modus:harness 开始工作。"
+        )
+        output = {
+            "continue": True,
+            "hookSpecificOutput": {
+                "hookEventName": "SessionStart",
+                "additionalContext": additional_context,
+            },
+        }
+
+    print(json.dumps(output, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/templates/hooks/stop-update-skills.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+"""
+Modus Stop Hook
+After the agent finishes responding, checks if any Harness active plans have
+new artifacts that haven't been reflected in Skills yet, and prompts the agent
+to trigger a knowledge write-back.
+"""
+import json
+import os
+import sys
+from datetime import datetime, timezone
+
+TRACKED_ARTIFACTS = [
+    "01-analysis.md",
+    "02-sprint-contract.md",
+    "03-test-report.md",
+    "04-perf-report.md",
+    "05-security-report.md",
+    "cr-report.md",
+    "07-deploy-status.md",
+]
+
+WRITEBACK_MARKER = ".skills-synced"
+
+
+def check_active_plans(project_dir: str) -> list[dict]:
+    """Returns list of {story_id, new_artifacts} for plans with unsynced artifacts."""
+    active_dir = os.path.join(project_dir, "modus", "plans", "active")
+    pending: list[dict] = []
+
+    if not os.path.isdir(active_dir):
+        return pending
+
+    for story_id in os.listdir(active_dir):
+        plan_dir = os.path.join(active_dir, story_id)
+        if not os.path.isdir(plan_dir):
+            continue
+
+        marker_path = os.path.join(plan_dir, WRITEBACK_MARKER)
+        last_sync = 0.0
+        if os.path.exists(marker_path):
+            last_sync = os.path.getmtime(marker_path)
+
+        new_artifacts = [
+            a for a in TRACKED_ARTIFACTS
+            if os.path.exists(os.path.join(plan_dir, a))
+            and os.path.getmtime(os.path.join(plan_dir, a)) > last_sync
+        ]
+
+        if new_artifacts:
+            pending.append({"story_id": story_id, "new_artifacts": new_artifacts})
+
+    return pending
+
+
+def main() -> int:
+    input_data = json.loads(sys.stdin.read())
+
+    # Avoid infinite loop: if a stop hook is already active, skip
+    if input_data.get("stop_hook_active"):
+        print(json.dumps({"continue": True}))
+        return 0
+
+    project_dir = os.environ.get("CODEBUDDY_PROJECT_DIR") or os.environ.get(
+        "CLAUDE_PROJECT_DIR", input_data.get("cwd", "")
+    )
+
+    pending = check_active_plans(project_dir)
+    if not pending:
+        print(json.dumps({"continue": True}))
+        return 0
+
+    lines = ["[Modus] 检测到以下 Harness 产出物尚未同步到 Skills 知识库："]
+    for item in pending:
+        lines.append(f"  Story {item['story_id']}: {', '.join(item['new_artifacts'])}")
+    lines.append(
+        "\n建议：调用 SubAgent 00（模式 D：知识提取）将新产出物的 [decision]/[guideline]/[pitfall] 回写到对应 Skill 文件。"
+        f"\n回写完成后请创建 {WRITEBACK_MARKER} 标记文件以避免重复提示。"
+    )
+
+    output = {
+        "continue": False,
+        "stopReason": "\n".join(lines),
+    }
+
+    print(json.dumps(output, ensure_ascii=False))
+    return 2  # exit code 2 → feedback injected into next agent message
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/templates/hooks-config.json

@@ -0,0 +1,83 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/session-start.py",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash|execute_command",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/pre-tool-use-safety.py",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit|write_to_file|replace_in_file",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/post-tool-use-lint.py",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|write_to_file|replace_in_file",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/post-tool-use-lint.py",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/stop-update-skills.py",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "auto",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/pre-compact-save.py",
+            "timeout": 15
+          }
+        ]
+      },
+      {
+        "matcher": "manual",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/pre-compact-save.py",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/rules/modus-constitution/RULE.mdc

@@ -0,0 +1,40 @@
+---
+description: Project constitution (hard rules) extracted from modus/config.yaml. Load this rule when implementing code, reviewing code, or running any Modus command that requires project-specific constraints. These rules override all other guidelines.
+alwaysApply: false
+enabled: true
+---
+
+# 项目宪法（Project Constitution）
+
+> 此规则由 `modus init` 根据 `modus/config.yaml` 中的 `constitution` 字段自动生成。
+> 如需修改，请编辑 `modus/config.yaml` 后重新运行 `modus update`。
+
+## 技术栈
+
+{{TECH_STACK}}
+
+## 构建命令
+
+```bash
+{{BUILD_COMMAND}}
+```
+
+## 测试命令
+
+```bash
+{{TEST_COMMAND}}
+```
+
+## 硬性约束（Hard Rules）
+
+以下规则在所有 Modus 命令执行时强制遵守，不因业务需要而妥协：
+
+{{HARD_RULES}}
+
+## 项目特有模式
+
+{{KEY_PATTERNS}}
+
+---
+
+*优先级：宪法 > Skill 建议 > 通用最佳实践*