@modus-ai/modus 0.1.0

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@modus-ai/modus",
+  "version": "0.1.0",
+  "description": "Modus — Business-grounded AI coding accelerator for CodeBuddy IDE",
+  "keywords": [
+    "ai",
+    "coding",
+    "codebuddy",
+    "agent",
+    "skill",
+    "harness"
+  ],
+  "homepage": "https://github.com/modus-ai/modus",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "bin": {
+    "modus": "bin/modus.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "templates",
+    "schemas"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "dev:cli": "node --loader ts-node/esm src/cli/index.ts",
+    "test": "vitest run",
+    "lint": "eslint src",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "chalk": "^5.3.0",
+    "inquirer": "^10.1.8",
+    "js-yaml": "^4.1.0",
+    "glob": "^11.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "@types/js-yaml": "^4.0.9",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0",
+    "eslint": "^9.0.0",
+    "ts-node": "^10.9.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/schemas/harness-schema.yaml

@@ -0,0 +1,91 @@
+# Modus Harness Schema
+# 定义 /modus:harness 双 Loop 多智能体流程的产出物及调度规则
+name: harness
+description: 双 Loop 多智能体 Harness — 全自动需求分析、开发、测试、评审、部署流程
+
+subAgents:
+  - id: "01"
+    skill: modus-harness-01-analysis
+    name: 需求分析
+    generates: 01-analysis.md
+    requires: []
+    loop: 1
+
+  - id: "02"
+    skill: modus-harness-02-dev
+    name: 代码开发
+    generates: 02-sprint-contract.md
+    requires: ["01"]
+    loop: 1
+    gateAfter: compile  # Gate A: 编译验证
+
+  - id: "03"
+    skill: modus-harness-03-test
+    name: 代码测试
+    generates: 03-test-report.md
+    requires: ["02"]
+    loop: 1
+    parallel: ["03", "04", "05"]  # 与 04/05 并行
+
+  - id: "04"
+    skill: modus-harness-04-perf
+    name: 性能审计
+    generates: 04-perf-report.md
+    requires: ["02"]
+    loop: 1
+    parallel: ["03", "04", "05"]
+
+  - id: "05"
+    skill: modus-harness-05-security
+    name: 安全审计
+    generates: 05-security-report.md
+    requires: ["02"]
+    loop: 1
+    parallel: ["03", "04", "05"]
+
+  - id: "06"
+    skill: modus-harness-06-review
+    name: 代码评审
+    generates: cr-report.md
+    requires: ["03", "04", "05"]  # Gate B: 等待 03/04/05 全部完成
+    loop: 2
+
+  - id: "07"
+    skill: modus-harness-07-deploy
+    name: 部署发布
+    generates: 07-deploy-status.md
+    requires: ["06"]
+    loop: 2
+    gateAfter: noPnPProblems  # Gate C: cr-report.md 无 P1/P2
+
+gates:
+  compile:
+    description: 编译验证
+    condition: "项目构建工具编译，exit code = 0"
+    onFail: retrySubAgent02
+    maxRetry: 3
+
+  noPnPProblems:
+    description: 代码评审质量门
+    condition: "cr-report.md 中 P1 和 P2 问题数量为 0"
+    onFail: retryFromSubAgent02
+    maxRetry: 3
+
+loop2:
+  trigger: "cr-report.md 中存在 P1 或 P2 问题"
+  action: "定位涉及的 Sprint，精准重入 SubAgent 02（非全量重跑）"
+  rerunPath: ["02", "Gate A", "03+04+05", "06"]
+  maxLoops: 3
+  onMaxLoopsReached: "暂停流程，上报用户，请求人工介入"
+
+finalReview:
+  trigger: "Gate C 通过（cr-report.md 无 P1/P2）"
+  action: "等待人工 Final Review，确认后合入主干"
+
+timeout:
+  perSubAgent: 15m
+  action: "汇报卡点，询问用户是否重试"
+
+directories:
+  active: modus/plans/active
+  archive: modus/plans/archive

package/schemas/knowledge-schema.yaml

@@ -0,0 +1,174 @@
+# Modus Knowledge Schema
+# 定义 knowledge-catalog.md 和 Skill frontmatter 的结构规范
+
+name: knowledge
+description: 知识体系 schema — 知识目录索引、Skill frontmatter、知识条目类型
+
+# ─────────────────────────────────────────
+# knowledge-catalog.md 结构
+# ─────────────────────────────────────────
+catalog:
+  location: modus/knowledge-catalog.md
+  description: 全景知识目录索引，所有命令启动时 Level 1 加载（~200 tokens）
+  fields:
+    - name: updated
+      type: date
+      description: 最后更新日期（YYYY-MM-DD）
+    - name: entries
+      type: list
+      description: 知识条目列表，每条一行摘要
+
+  entry_format: "- **{skill-name}**: {描述} [maturity: {level}] {time_field}: {date} {optional_warning}"
+  example: |
+    - **modus-biz-order**: 订单域 — 创建/流转/查询 [maturity: verified] 最近引用: 2026-04-18
+    - **modus-tech-wiki**: 跨项目架构决策/反模式库 [maturity: draft] ⚠️ 6个月未引用，可能过时
+
+# ─────────────────────────────────────────
+# Skill frontmatter 字段
+# ─────────────────────────────────────────
+skill_frontmatter:
+  fields:
+    - name: name
+      type: string
+      required: true
+      description: Skill 唯一标识符（目录名）
+      example: "modus-biz-order"
+
+    - name: description
+      type: string
+      required: true
+      description: 一句话描述，必须包含对应标记前缀
+      markers:
+        biz: "[MODUS:BIZ]"
+        tech: "[MODUS:TECH]"
+        team: "[MODUS:TEAM]"
+      example: "[MODUS:BIZ] 订单业务知识 — 订单创建/状态流转/查询"
+
+    - name: version
+      type: semver
+      required: true
+      description: Skill 版本，更新时自增 minor（如 1.0.0 → 1.1.0）
+
+    - name: updated
+      type: date
+      required: true
+      description: 最后更新日期
+
+    - name: maturity
+      type: enum
+      required: true
+      values: [draft, verified, proven]
+      description: |
+        知识成熟度：
+        draft    — 初始状态，单一来源，未经工作流验证
+        verified — 单项目验证，已在 ≥1 个工作流中被引用
+        proven   — 成熟可信赖，已在 ≥2 个工作流中验证
+      default: draft
+
+    - name: last_referenced
+      type: date
+      required: true
+      description: 最近一次被工作流引用的日期，用于衰减计算
+
+    - name: usage_count
+      type: integer
+      required: true
+      description: 被工作流引用的累计次数
+      default: 0
+
+    - name: layer
+      type: string
+      required: false
+      description: 知识层级（仅 team-conventions 和 tech-wiki 需要填写）
+      values: ["0-T", "1"]
+
+# ─────────────────────────────────────────
+# 知识条目类型（五类 MECE）
+# ─────────────────────────────────────────
+knowledge_types:
+  - tag: "[model]"
+    description: 实体定义、数据结构、关系图、枚举
+    examples:
+      - "Order 实体的核心字段（id, status, tenantId, amount）"
+      - "OrderStatus 枚举：CREATED/PAID/COMPLETED/CANCELLED"
+
+  - tag: "[decision]"
+    description: 技术选型、架构决策及其理由
+    examples:
+      - "选择事件驱动而非 RPC 同步，原因：解耦、削峰、避免级联失败"
+
+  - tag: "[guideline]"
+    description: 推荐（recommend）或禁止（avoid）的做法
+    polarity_values: [recommend, avoid]
+    examples:
+      - "recommend: AopContext.currentProxy() 解决同类方法事务调用"
+      - "avoid: 在 Controller 层写业务逻辑"
+
+  - tag: "[pitfall]"
+    description: 已知风险、故障模式、排查步骤
+    examples:
+      - "批量操作不加分页保护，数据量大时内存溢出"
+      - "多线程下 ThreadLocal 数据未清理导致租户数据串扰"
+
+  - tag: "[process]"
+    description: 业务流程、状态机、操作步骤
+    examples:
+      - "订单状态流转：CREATED→PAID→COMPLETED（单向，不可逆）"
+      - "支付回调：验签→幂等检查→状态更新→MQ 通知"
+
+# ─────────────────────────────────────────
+# 成熟度提升与衰减规则
+# ─────────────────────────────────────────
+maturity_lifecycle:
+  promotion:
+    draft_to_verified:
+      condition: "usage_count >= 1（在 1 个工作流中被成功引用）"
+      action: "更新 maturity: verified，更新 last_referenced"
+    verified_to_proven:
+      condition: "usage_count >= 2 且来自不同工作流（跨工作流验证）"
+      action: "更新 maturity: proven，更新 last_referenced"
+
+  decay:
+    proven_decay:
+      condition: "proven 且距 last_referenced 超过 12 个月"
+      action: "降为 verified，追加注释 ⚠️ 12个月未引用，请验证是否仍然适用"
+    verified_decay:
+      condition: "verified 且距 last_referenced 超过 6 个月"
+      action: "降为 draft，追加注释 ⚠️ 6个月未引用，可能已过时"
+
+  decay_check_trigger:
+    - "00-skills-builder 模式 D 执行时"
+    - "可手动触发：/modus:init --lint"
+
+# ─────────────────────────────────────────
+# HANDOFF 块格式（Harness 产物交接协议）
+# ─────────────────────────────────────────
+handoff_block:
+  description: 每个 Harness SubAgent 产出物文件头部的机器可读摘要，Orchestrator 只读此块决策
+  format: |
+    <!--HANDOFF
+    agent: "{agent-id}"
+    story_id: "{story-id}"
+    domains: ["{domain1}", "{domain2}"]
+    sprint_count: {N}
+    risk_level: "low|medium|high"
+    key_constraints:
+      - "{约束1}"
+    skill_refs:
+      - "{skill-name}@{version}"
+    gate_status: "passed|failed|pending"
+    issues: []
+    -->
+  fields:
+    - name: agent
+      description: 产出此文件的 SubAgent ID
+    - name: domains
+      description: 本次涉及的业务域列表
+    - name: risk_level
+      description: 风险等级，影响 SubAgent 06 审查力度
+    - name: gate_status
+      description: 当前产物的 Gate 状态
+    - name: issues
+      description: P1/P2 问题列表（cr-report 专用），空则表示通过 Gate C
+    - name: skill_refs
+      description: 引用的 Skill 版本，用于 ARCHIVE 阶段来源追溯

package/schemas/plan-schema.yaml

@@ -0,0 +1,42 @@
+# Modus Plan Schema
+# 定义 /modus:plan 命令的产出物及依赖关系
+name: plan
+description: 功能规划模式 — 生成 proposal、design、tasks 三件套
+
+artifacts:
+  - id: proposal
+    generates: proposal.md
+    requires: []
+    description: 意图与范围文档，描述为什么做、做什么、不做什么
+
+  - id: design
+    generates: design.md
+    requires: [proposal]
+    description: 技术方案文档，描述怎么做、架构决策、文件变更清单
+
+  - id: tasks
+    generates: tasks.md
+    requires: [proposal, design]
+    description: 实现清单，按层次拆分为可执行的 checkbox 任务
+
+# 产出物依赖图：
+#
+#   proposal
+#      │
+#      └──► design
+#               │
+#               └──► tasks
+#
+# 说明：
+# - proposal 是起点，无依赖
+# - design 依赖 proposal（需要理解意图才能设计技术方案）
+# - tasks 依赖 proposal + design（需要完整的 what 和 how 才能拆分任务）
+
+archive:
+  targetDir: modus/plans/archive
+  namePattern: "{YYYY-MM-DD}-{name}"
+  preserveAll: true
+
+directories:
+  active: modus/plans
+  archive: modus/plans/archive

package/schemas/spec-schema.yaml

@@ -0,0 +1,64 @@
+# Modus Spec Schema
+# 定义 /modus:spec 命令的产出物及依赖关系
+name: spec
+description: OpenSpec 规范驱动开发模式 — 生成 proposal、delta specs、design、tasks 四件套
+
+artifacts:
+  - id: proposal
+    generates: proposal.md
+    requires: []
+    description: 意图与范围文档，同 plan 模式
+
+  - id: specs
+    generates: "specs/{domain}/spec.md"
+    requires: [proposal]
+    description: |
+      Delta 规格文档，使用 ADDED/MODIFIED/REMOVED 三段式描述行为变更。
+      只描述「系统做什么」（WHAT），不涉及实现细节（HOW）。
+      每个 Requirement 必须有至少一个可测试的 Scenario。
+
+  - id: design
+    generates: design.md
+    requires: [proposal]
+    description: 技术方案文档，可与 specs 并行生成
+
+  - id: tasks
+    generates: tasks.md
+    requires: [specs, design]
+    description: 实现清单，末尾额外包含「规格验证」任务
+
+# 产出物依赖图：
+#
+#        proposal
+#           │
+#     ┌─────┴─────┐
+#     ▼           ▼
+#   specs       design
+#     │           │
+#     └─────┬─────┘
+#           ▼
+#         tasks
+#
+# 说明：
+# - proposal 是起点
+# - specs 和 design 可并行生成（都只依赖 proposal）
+# - tasks 需要 specs + design 都完成后才能生成
+
+delta:
+  sections:
+    - ADDED Requirements    # 新增行为 → 归档时追加到主 spec
+    - MODIFIED Requirements # 修改行为 → 归档时替换主 spec 中对应条目
+    - REMOVED Requirements  # 废弃行为 → 归档时从主 spec 中删除
+
+  mergeTarget: modus/specs  # delta 归档后合并到此目录
+
+archive:
+  targetDir: modus/changes/archive
+  namePattern: "{YYYY-MM-DD}-{name}"
+  mergeDeltaOnArchive: true  # 归档时自动合并 delta specs 到主规格库
+  preserveAll: true
+
+directories:
+  active: modus/changes
+  archive: modus/changes/archive
+  specs: modus/specs          # 主规格库（source of truth）

package/templates/commands/harness.md

@@ -0,0 +1,46 @@
+# /modus:harness
+
+Full dual-loop multi-agent Harness. Automated end-to-end development flow from requirements analysis to deployment.
+
+## Instructions
+
+Read and follow the skill at `.codebuddy/skills/modus-harness/SKILL.md` to execute this command.
+
+## Quick Summary
+
+1. Check for business Skills — if absent, strongly recommend running `/modus:init` first
+2. Accept TAPD Story URL as input
+3. Create working directory: `modus/plans/active/{story-id}/`
+4. Run the Harness Orchestrator which coordinates 7 SubAgents:
+
+**Loop 1 (sequential):**
+- SubAgent 01: Requirements analysis → `01-analysis.md`
+- SubAgent 02: Code development → `02-sprint-contract.md` + code changes
+- Gate A: Build compilation check
+- SubAgent 03/04/05 (parallel): Tests + Performance audit + Security audit
+- Gate B: Wait for all 3 reports
+
+**Loop 2 (quality gate):**
+- SubAgent 06: Code review → `cr-report.md`
+- If P1/P2 found → precise re-entry to SubAgent 02 → repeat
+- Gate C: No P1/P2 → proceed
+- SubAgent 07: Deployment verification → `07-deploy-status.md`
+
+5. Final Review: human confirms before merging
+
+## Working Directory
+
+```
+modus/plans/active/{story-id}/
+├── 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
+```
+
+## Resume Support
+
+If `modus/plans/active/{story-id}/` already contains partial artifacts, resume from the last completed SubAgent.

package/templates/commands/init.md

@@ -0,0 +1,16 @@
+# /modus:init
+
+Analyze the project codebase, classify it by business domains, and generate business Skill files for each domain.
+
+## Instructions
+
+Read and follow the skill at `.codebuddy/skills/modus-init/SKILL.md` to execute this command.
+
+## Quick Summary
+
+1. Scan the project structure and identify business domains
+2. Present the domain classification to the user for confirmation
+3. For each confirmed domain, generate `.codebuddy/skills/modus-biz-{domain}/SKILL.md`
+4. Report completion
+
+If `.codebuddy/skills/modus-biz-*` directories already exist, offer to update or rebuild them.

package/templates/commands/plan.md

@@ -0,0 +1,28 @@
+# /modus:plan
+
+Plan mode. Generate structured planning documents (proposal, design, tasks) backed by up-to-date business Skills.
+
+## Instructions
+
+Read and follow the skill at `.codebuddy/skills/modus-plan/SKILL.md` to execute this command.
+
+## Quick Summary
+
+1. Check for business Skills (same fallback as `/modus:vibe`)
+2. Identify relevant business domains from the user's request
+3. **Pre-update Skills**: refresh relevant business Skill files based on latest code
+4. Generate planning documents to `modus/plans/{name}/`:
+   - `proposal.md` — intent and scope
+   - `design.md` — technical approach and decisions
+   - `tasks.md` — implementation checklist
+5. Ask user whether to archive → move to `modus/plans/archive/{YYYY-MM-DD}-{name}/`
+6. **Post-update Skills**: write back new knowledge discovered during planning
+
+## Output Location
+
+```
+modus/plans/{name}/
+├── proposal.md
+├── design.md
+└── tasks.md
+```

package/templates/commands/spec.md

@@ -0,0 +1,37 @@
+# /modus:spec
+
+OpenSpec-style spec-driven development. Generate behavior specifications (delta specs) + design + tasks, with archive merging specs into the main spec library.
+
+## Instructions
+
+Read and follow the skill at `.codebuddy/skills/modus-spec/SKILL.md` to execute this command.
+
+## Quick Summary
+
+1. Check for business Skills (same fallback as `/modus:vibe`)
+2. Identify relevant business domains
+3. **Pre-update Skills**: refresh relevant business Skill files
+4. Generate specification documents to `modus/changes/{name}/`:
+   - `proposal.md` — intent and scope
+   - `specs/{domain}/spec.md` — delta specs (ADDED/MODIFIED/REMOVED requirements with Scenarios)
+   - `design.md` — technical approach
+   - `tasks.md` — implementation checklist (includes spec verification tasks)
+5. Ask user whether to archive:
+   - Delta specs merged into `modus/specs/` (source of truth)
+   - Change folder moved to `modus/changes/archive/{YYYY-MM-DD}-{name}/`
+6. **Post-update Skills**: write back new business rules and contracts
+
+## Delta Spec Format
+
+Use ADDED/MODIFIED/REMOVED sections with GIVEN/WHEN/THEN scenarios.
+Specs describe WHAT the system does, not HOW.
+
+## Output Location
+
+```
+modus/changes/{name}/
+├── proposal.md
+├── specs/{domain}/spec.md    ← delta specs
+├── design.md
+└── tasks.md
+```

package/templates/commands/vibe.md

@@ -0,0 +1,18 @@
+# /modus:vibe
+
+Context-aware vibe coding. Load relevant business Skills before coding so AI works as a knowledgeable project member.
+
+## Instructions
+
+Read and follow the skill at `.codebuddy/skills/modus-vibe/SKILL.md` to execute this command.
+
+## Quick Summary
+
+1. Check if `.codebuddy/skills/modus-biz-*` directories exist
+   - If not: offer to run `/modus:init` or continue in degraded mode
+2. Match user's prompt to relevant business domains
+3. Confirm domain selection with user
+4. Load the selected Skill files as context
+5. Execute the coding task with business context
+
+**Degraded mode** (no business Skills): proceed without domain context, but note that code quality may be lower without project-specific knowledge.

package/templates/knowledge-catalog.md

@@ -0,0 +1,26 @@
+# Modus 知识全景目录
+# 所有 Modus 命令启动时先读此文件（Level 1 加载，~200 tokens）
+# 按需再读完整 SKILL.md（Level 2），或直接读代码文件（Level 3）
+#
+# maturity: draft → verified → proven
+# 衰减：proven 12个月未引用→verified；verified 6个月未引用→draft
+
+updated: {YYYY-MM-DD}
+
+## 团队约定 (Layer 0-T)
+- **modus-team-conventions**: 代码规范/提交规范/硬性约束 [maturity: draft] 更新: {日期}
+
+## 技术知识 (Layer 1)
+- **modus-tech-wiki**: 跨项目架构决策/反模式库/性能优化 [maturity: draft] 更新: {日期}
+
+## 业务知识 (Layer 2)
+<!-- 由 /modus:init 生成，由各模式工作流自动更新 -->
+- **modus-biz-{domain}**: {中文域名} — {核心职责一句话} [maturity: draft] 最近引用: {日期}
+
+## 渐进加载说明
+启动任意 Modus 命令时的加载顺序：
+  Level 1（必须，~200 tokens）: 读本文件，了解有哪些知识可用
+  Level 2（按需，~3000 tokens/个）: 根据任务匹配相关域，读对应 SKILL.md
+  Level 3（按需，无上限）: 执行任务时读 Skill 引用的实际代码文件
+
+目标：不相关的 Skill 不加载，大幅降低 token 消耗。