moluoxixi-ai-rules 0.2.7 → 0.2.8

package/README-en.md

@@ -2,7 +2,7 @@
 
 [简体中文](README.md) | English
 
-AIRules distributes versioned role capabilities to AI coding hosts. A role is more than a prompt collection: it is an installable composition of shared skills, MCP servers, a role CLI, project workflows, agents, hooks, and runtime assets.
+AIRules distributes versioned role capabilities to AI hosts. A role combines the shared skills, MCP servers, role CLI, project workflows, agents, hooks, and runtime assets it needs.
 
 There are two installation layers:
 
@@ -11,9 +11,50 @@ There are two installation layers:
 
 The AIRules installer handles user-level package setup, asset distribution, and managed skill/MCP verification, but it does not dispatch agents. The initialized Moluoxixi or Trellis main workflow owns dispatch, hooks inject state and context, and skills perform semantic work and file changes.
 
+## `general`
+
+For users who need to question plans, remember decisions across sessions, and organize documents. It also provides the shared base for development roles.
+
+### Install
+
+```bash
+npm install --global moluoxixi-ai-rules
+airules install general --host all
+airules verify general --host all
+```
+
+### Features
+
+`general` selects `common` and `grilling`, providing five skills and the Hindsight memory MCP:
+
+| Skill | Purpose |
+| --- | --- |
+| `grilling` | Question plans, decisions, and assumptions to establish tradeoffs and validation criteria |
+| `hindsight-memory` | Recall and retain confirmed project knowledge and connect memory visualization |
+| `hindsight-docs` | Consult Hindsight API, deployment, and configuration documentation |
+| `create-skill` | Create or revise a reusable agent skill |
+| `spec-organization` | Organize document directories, indexes, and links |
+
+The default MCP endpoint is `http://localhost:8888/mcp/`. The official Hindsight console at `http://localhost:9999` shows facts, source documents, and entity relationships. Connect a standalone console to an existing API, or use the bundled Docker Compose assets for a new deployment. Model settings live in the user configuration directory and data persists in a named volume. See [memory visualization](capabilities/common/skills/hindsight-memory/references/visualization.md).
+
+`moluoxixi`, `trellis`, and `matt` inherit these capabilities with `extends_roles: [general]`. Installing a development role includes its inherited capabilities. See [General](roles/general/README.md) and [role inheritance](capabilities/README.md#角色继承).
+
+### Usage
+
+Describe the goal or name a skill directly:
+
+```text
+Use grilling to question this plan and check its assumptions and tradeoffs.
+Remember our confirmed decisions, reasoning, and next validation criteria.
+Recall this project's earlier decisions and check whether they still apply.
+Open this project's memory visualization to inspect facts and entity relationships.
+```
+
+Roles share the same Hindsight API and project bank. Start the service using the deployment guide and verify memory reads and writes before using it.
+
 ## `moluoxixi`
 
-For users who want a complete AI development workflow with the native Moluoxixi CLI, project knowledge, multi-domain skills, and controlled multi-agent dispatch.
+For users who want a complete AI development workflow with the native Moluoxixi CLI, project knowledge, multi-domain skills, and controlled multi-agent dispatch. It inherits `general` and adds `coding`, `productivity`, and `frontend`.
 
 ### Install
 
@@ -43,7 +84,7 @@ npm install --global @moluoxixi/airules-moluoxixi-cli
 | Layer | Assets | Responsibility |
 | --- | --- | --- |
 | User-level role | Moluoxixi core, `moluoxixi`/`ml`, `init-project` | Native initialization, update, task, memory, workflow, and channel commands |
-| Shared capabilities | `common`, `coding`, `productivity`, `frontend` | Shared and pinned external skills plus MCP servers |
+| Shared capabilities | Inherited `common`, `grilling`; own `coding`, `productivity`, `frontend` | Shared and pinned external skills plus MCP servers |
 | Native project | `.moluoxixi/workflow.md`, `tasks/`, `spec/`, `scripts/`, `agents/`, host configuration | Workflow state, task artifacts, project rules, and agent definitions |
 | AIRules project extension | `.moluoxixi/knowledge/`, knowledge runtime and hook, `moluoxixi-knowledge` | Source change detection and traceable project knowledge |
 
@@ -75,7 +116,7 @@ Project workflow entries become slash commands or discoverable skills according
 | `common` | `hindsight-docs` | Look up Hindsight API, deployment, and advanced configuration |
 | `frontend` | `frontend-design` | Give intentional visual direction when creating or reshaping interfaces |
 | `productivity` | `grill-me` | Start a rigorous interview that turns an idea into an executable plan |
-| `productivity` | `grilling` | Stress-test plans, decisions, and designs |
+| `grilling` | `grilling` | Inherited from `general`; stress-test plans, decisions, and designs |
 | `productivity` | `handoff` | Compress the conversation into a document another agent can resume |
 | `productivity` | `teach` | Run stateful teaching across sessions in the current repository |
 | `productivity` | `to-questionnaire` | Turn unresolved decisions into a questionnaire for an informed person |
@@ -134,7 +175,7 @@ Role source: [`roles/moluoxixi`](roles/moluoxixi).
 
 ## `matt`
 
-For users who want Matt Pocock's engineering and productivity methods without a fixed project workflow, project agents, hooks, MCP servers, or a role CLI.
+For users who want Matt Pocock's engineering and productivity methods together with shared grilling and memory capabilities.
 
 ### Install
 
@@ -148,12 +189,16 @@ airules verify matt --host all
 
 #### Installed assets
 
-`matt` composes only the `engineering` and `productivity` capabilities. It installs pinned upstream skills but creates no `.matt/` directory and has no role-owned `init-project`, agents, hooks, CLI, or MCP server.
+`matt` inherits `common` and `grilling` from `general`, then adds its own `engineering` and `productivity` capabilities. Shared skills and the Hindsight MCP are installed with the role and use the same project bank as other roles. See [memory visualization](capabilities/common/skills/hindsight-memory/references/visualization.md) for console setup. Engineering and productivity skills use a pinned upstream revision; the role requires no project initialization.
 
 #### Skills
 
 | Capability | Skill | Purpose |
 | --- | --- | --- |
+| `common` | `create-skill` | Create or revise a reusable agent skill |
+| `common` | `spec-organization` | Organize document directories, indexes, and links |
+| `common` | `hindsight-memory` | Retain and recall project memory and connect the official console |
+| `common` | `hindsight-docs` | Consult Hindsight API and deployment documentation |
 | `engineering` | `ask-matt` | Explicit router that selects the appropriate Matt skill or flow |
 | `engineering` | `code-review` | Review changes since a baseline against standards and specification |
 | `engineering` | `codebase-design` | Improve module boundaries, interfaces, and testability using deep-module principles |
@@ -173,7 +218,7 @@ airules verify matt --host all
 | `engineering` | `wayfinder` | Plan work larger than one agent session as a decision and ticket map |
 | `engineering` | `wizard` | Generate an interactive Bash wizard for human-only credentials, consoles, or migrations |
 | `productivity` | `grill-me` | Start a rigorous planning interview |
-| `productivity` | `grilling` | Stress-test a plan, decision, or design |
+| `grilling` | `grilling` | Inherited from `general`; stress-test a plan, decision, or design |
 | `productivity` | `handoff` | Produce a resumable cross-agent handoff |
 | `productivity` | `teach` | Teach across sessions with recorded state |
 | `productivity` | `to-questionnaire` | Turn unknowns into a questionnaire for an informed person |
@@ -195,13 +240,13 @@ Turn this proposal into a spec, then use to-tickets to split the work.
 Implement this behavior with tdd, then run code-review.
 ```
 
-A typical extended chain is `setup-matt-pocock-skills -> to-spec -> to-tickets -> implement -> code-review`; isolated problems can invoke one skill directly. The host, repository documents, or issue tracker owns state, and AIRules creates no `.matt/` directory.
+A typical extended chain is `setup-matt-pocock-skills -> to-spec -> to-tickets -> implement -> code-review`; isolated problems can invoke one skill directly. The host, repository documents, or issue tracker owns task state. Confirmed reusable decisions can be retained with `hindsight-memory`.
 
 Role source: [`roles/matt`](roles/matt).
 
 ## `trellis`
 
-For users who want the native Trellis task-and-specification workflow together with AIRules shared skills, MCP, project knowledge, and multi-agent dispatch.
+For users who want the native Trellis task-and-specification workflow together with AIRules shared skills, MCP, project knowledge, and multi-agent dispatch. It inherits `general` and adds `coding`, `productivity`, and `frontend`.
 
 ### Install
 
@@ -221,7 +266,7 @@ The role install provides the Trellis CLI and user-level capabilities but does n
 | Layer | Assets | Responsibility |
 | --- | --- | --- |
 | User-level role | Trellis CLI and `init-project` | Native `init/update/upgrade/uninstall/mem/workflow/platforms/channel` commands |
-| Shared capabilities | `common`, `coding`, `productivity`, `frontend` | The same shared skills, pinned external skills, and MCP servers as Moluoxixi |
+| Shared capabilities | Inherited `common`, `grilling`; own `coding`, `productivity`, `frontend` | The same shared skills, pinned external skills, and MCP servers as Moluoxixi |
 | Native project | `.trellis/workflow.md`, `tasks/`, `spec/`, `scripts/`, `agents/`, host configuration | Plan/Execute/Finish state, task artifacts, specs, and agent definitions |
 | AIRules project extension | `.trellis/knowledge/`, knowledge runtime and hook, `trellis-knowledge` | Source change detection and bidirectionally traceable knowledge |
 
@@ -251,7 +296,7 @@ Native Trellis projects workflow entries as commands or skills according to host
 | `common` | `hindsight-docs` | Look up Hindsight API, deployment, and advanced configuration |
 | `frontend` | `frontend-design` | Guide intentional frontend design and redesign |
 | `productivity` | `grill-me` | Start a rigorous requirements interview |
-| `productivity` | `grilling` | Stress-test plans, decisions, and designs |
+| `grilling` | `grilling` | Inherited from `general`; stress-test plans, decisions, and designs |
 | `productivity` | `handoff` | Produce a cross-agent handoff |
 | `productivity` | `teach` | Teach across sessions with recorded progress |
 | `productivity` | `to-questionnaire` | Turn unresolved questions into a questionnaire |
@@ -301,10 +346,13 @@ Role source: [`roles/trellis`](roles/trellis).
 
 Shared skills, MCP catalogs, and vendor declarations live together in `capabilities/<capability>/`, such as `capabilities/common/skills/`. Each capability is a data-only directory containing `capability.yaml`, skills, MCP catalogs, and documentation; roles select capabilities in `role.yaml`. The runtime loader lives in `scripts/lib/capabilities.ts`, composes vendors in declaration order, merges compatible projections, deduplicates identical projections, and rejects source or target conflicts. See [capabilities/README.md](capabilities/README.md) for the layout and complete mapping.
 
+`extends_roles` recursively combines parent capabilities before the child's own choices. Shared ancestors and capabilities are deduplicated; missing parents and inheritance cycles are rejected. A parent may be a declaration-only template. The child declares its own role vendor, hosts, and CLI packages. See [role inheritance](capabilities/README.md#角色继承).
+
 Host directories, aliases, skill projection switches, and MCP formats are declared in [hosts/hosts.yaml](hosts/hosts.yaml). `scripts/lib/hosts.ts` loads and validates the declaration and resolves paths; declaration types live in `scripts/lib/types/`. Adding a host only requires a YAML entry. See [hosts/README.md](hosts/README.md) for fields and maintenance guidance.
 
 ```text
 role manifest
+  -> role inheritance and capability composition
   -> pinned vendor checkout / package setup
   -> vendor staging
   -> canonical ~/.agents/skills

package/README.md

@@ -2,7 +2,7 @@
 
 简体中文 | [English](README-en.md)
 
-AIRules 为 AI 编程宿主分发带版本的角色能力。一个 role 不只是“一组提示词”，而是由共享 skills、MCP servers、角色 CLI、项目工作流、agents、hooks 和运行时资产组成的可安装组合。
+AIRules 为 AI 宿主分发带版本的角色能力。一个 role 按需组合共享 skills、MCP servers、角色 CLI、项目工作流、agents、hooks 和运行时资产。
 
 先区分两个安装层级：
 
@@ -11,9 +11,50 @@ AIRules 为 AI 编程宿主分发带版本的角色能力。一个 role 不只
 
 AIRules 安装器负责用户级 package setup、资产分发和受管 skills/MCP 校验，但不调度 agents。agents 的派发权属于初始化后的 Moluoxixi/Trellis 主工作流，hooks 负责注入状态和上下文，skills 才负责语义分析与文件修改。
 
+## `general`
+
+适合需要计划审问、跨会话记忆和文档整理的用户，也是开发角色共享的基础角色。
+
+### 安装
+
+```bash
+npm install --global moluoxixi-ai-rules
+airules install general --host all
+airules verify general --host all
+```
+
+### 功能
+
+`general` 选择 `common` 和 `grilling`，提供五项 skills 和 Hindsight 记忆 MCP：
+
+| Skill | 做什么 |
+| --- | --- |
+| `grilling` | 审问计划、决策和假设，明确取舍与验证条件 |
+| `hindsight-memory` | 按项目回忆和保存已确认的信息，连接记忆可视化 |
+| `hindsight-docs` | 查询 Hindsight API、部署和高级配置文档 |
+| `create-skill` | 创建或修订可复用的 agent skill |
+| `spec-organization` | 整理文档目录、索引和链接 |
+
+Hindsight MCP 默认连接 `http://localhost:8888/mcp/`。官方控制台默认位于 `http://localhost:9999`，可查看记忆事实、来源文档和实体关系图。已有 API 可单独启动控制台；首次部署可使用随 skill 分发的 Docker Compose，模型配置和数据分别保存在用户配置目录与持久化卷中。步骤见 [记忆可视化](capabilities/common/skills/hindsight-memory/references/visualization.md)。
+
+`moluoxixi`、`trellis` 和 `matt` 通过 `extends_roles: [general]` 继承这些通用能力；安装开发角色时会一并安装。声明与规则见 [General](roles/general/README.md) 和 [角色继承](capabilities/README.md#角色继承)。
+
+### 用法
+
+直接在宿主中描述目标或点名 skill：
+
+```text
+请用 grilling 审问这个计划，逐项检查假设和取舍。
+请记住我们已确认的结论、理由和下一步验证条件。
+回忆这个项目之前的决定，并核对是否仍适用。
+打开当前项目的记忆可视化，查看事实和实体关系图。
+```
+
+不同角色使用同一 Hindsight 服务和项目 bank，复用已确认的记忆。使用记忆前按上述部署说明启动服务并验证读写。
+
 ## `moluoxixi`
 
-适合希望获得完整 AI 开发流程，同时需要 Moluoxixi 原生 CLI、项目知识库、多领域 skills 和可控多 agent 调度的用户。
+适合希望获得完整 AI 开发流程，同时需要 Moluoxixi 原生 CLI、项目知识库、多领域 skills 和可控多 agent 调度的用户。继承 `general`，再增加 `coding`、`productivity` 和 `frontend`。
 
 ### 安装
 
@@ -43,7 +84,7 @@ npm install --global @moluoxixi/airules-moluoxixi-cli
 | 层级 | 资产 | 作用 |
 | --- | --- | --- |
 | 用户级角色资产 | Moluoxixi core、`moluoxixi`/`ml` CLI、`init-project` | 提供原生项目初始化、更新、任务、memory、workflow 和 channel 命令 |
-| 公共 capability | `common`、`coding`、`productivity`、`frontend` | 组合共享 skills、外部固定版本 skills 和 MCP servers |
+| 公共 capability | 继承的 `common`、`grilling`；自身的 `coding`、`productivity`、`frontend` | 组合共享 skills、外部固定版本 skills 和 MCP servers |
 | 原生项目资产 | `.moluoxixi/workflow.md`、`tasks/`、`spec/`、`scripts/`、`agents/`、宿主配置 | 保存工作流状态、任务工件、项目规范和 agent 定义 |
 | AIRules 项目扩展 | `.moluoxixi/knowledge/`、知识 runtime、宿主 knowledge hook、`moluoxixi-knowledge` | 检测 source 变化，维护可追踪的项目知识库 |
 
@@ -75,7 +116,7 @@ npm install --global @moluoxixi/airules-moluoxixi-cli
 | `common` | `hindsight-docs` | 查询 Hindsight API、部署和高级配置文档 |
 | `frontend` | `frontend-design` | 为新 UI 或现有界面重塑提供有明确审美方向的设计指导 |
 | `productivity` | `grill-me` | 启动严格访谈，把模糊想法推进到可执行方案 |
-| `productivity` | `grilling` | 压力测试计划、决策或设计中的薄弱假设 |
+| `grilling` | `grilling` | 从 `general` 继承，压力测试计划、决策或设计中的薄弱假设 |
 | `productivity` | `handoff` | 把当前对话压缩为下一位 agent 可接手的交接文档 |
 | `productivity` | `teach` | 在当前仓库中进行可跨会话记录状态的教学 |
 | `productivity` | `to-questionnaire` | 把 agent 无法独立回答的决策转成给知情人的问卷 |
@@ -141,7 +182,7 @@ SubagentStart
 
 ## `matt`
 
-适合只想安装 Matt Pocock 的工程方法和效率 skills，不需要固定项目工作流、项目 agents、hooks、MCP 或角色 CLI 的用户。
+适合需要 Matt Pocock 工程方法和效率 skills，并希望复用通用审问和记忆能力的用户。
 
 ### 安装
 
@@ -155,12 +196,16 @@ airules verify matt --host all
 
 #### 安装后的资产
 
-`matt` 只组合 `engineering` 和 `productivity` 两个 capability。它安装固定上游版本的 skills，但不创建 `.matt/`，没有 role-owned `init-project`、agents、hooks、CLI 或 MCP server。
+`matt` 继承 `general` 的 `common` 和 `grilling`，再组合自身的 `engineering` 和 `productivity`。通用 skills 和 Hindsight MCP 随角色安装，项目 bank 与其它角色共用；控制台部署见 [记忆可视化](capabilities/common/skills/hindsight-memory/references/visualization.md)。工程和效率 skills 固定上游版本，角色无需项目初始化。
 
 #### Skills
 
 | Capability | Skill | 做什么 |
 | --- | --- | --- |
+| `common` | `create-skill` | 创建或修订可复用的 agent skill |
+| `common` | `spec-organization` | 整理文档目录、索引和链接 |
+| `common` | `hindsight-memory` | 保存和检索项目记忆，连接官方可视化控制台 |
+| `common` | `hindsight-docs` | 查询 Hindsight API 和部署文档 |
 | `engineering` | `ask-matt` | 根据当前问题选择适合的 Matt skill 或工作流；这是显式调用的路由器 |
 | `engineering` | `code-review` | 从指定基线对改动做 standards 与 spec 双轴审查 |
 | `engineering` | `codebase-design` | 用深模块原则改进模块边界、接口和可测试性 |
@@ -180,7 +225,7 @@ airules verify matt --host all
 | `engineering` | `wayfinder` | 把超出单次会话的大型工作规划成决策与 ticket 地图 |
 | `engineering` | `wizard` | 生成交互式 bash wizard，引导人工完成凭据、控制台或迁移步骤 |
 | `productivity` | `grill-me` | 启动严格访谈，把模糊计划推进到可执行状态 |
-| `productivity` | `grilling` | 压力测试计划、决策或设计 |
+| `grilling` | `grilling` | 从 `general` 继承，压力测试计划、决策或设计 |
 | `productivity` | `handoff` | 生成下一位 agent 可直接接手的交接文档 |
 | `productivity` | `teach` | 在仓库中进行可记录进度的跨会话教学 |
 | `productivity` | `to-questionnaire` | 把未决问题转成面向知情人的问卷 |
@@ -202,13 +247,13 @@ airules verify matt --host all
 请使用 tdd 实现这个行为，最后运行 code-review。
 ```
 
-一条典型链路是 `setup-matt-pocock-skills -> to-spec -> to-tickets -> implement -> code-review`；单点问题则直接使用对应 skill。所有状态由当前宿主、仓库文档或 issue tracker 管理，AIRules 不创建 `.matt/`。
+一条典型链路是 `setup-matt-pocock-skills -> to-spec -> to-tickets -> implement -> code-review`；单点问题则直接使用对应 skill。任务状态由当前宿主、仓库文档或 issue tracker 管理，已确认的可复用结论可通过 `hindsight-memory` 保存。
 
 角色源码位于 [`roles/matt`](roles/matt)。
 
 ## `trellis`
 
-适合希望使用原生 Trellis 的任务与规范驱动工作流，同时获得 AIRules 共享 skills、MCP、知识库和多 agent 调度的用户。
+适合希望使用原生 Trellis 的任务与规范驱动工作流，同时获得 AIRules 共享 skills、MCP、知识库和多 agent 调度的用户。继承 `general`，再增加 `coding`、`productivity` 和 `frontend`。
 
 ### 安装
 
@@ -228,7 +273,7 @@ trellis --version
 | 层级 | 资产 | 作用 |
 | --- | --- | --- |
 | 用户级角色资产 | Trellis CLI、`init-project` | 提供原生 `init/update/upgrade/uninstall/mem/workflow/platforms/channel` 命令 |
-| 公共 capability | `common`、`coding`、`productivity`、`frontend` | 与 Moluoxixi 相同的共享 skills、外部固定版本 skills 和 MCP servers |
+| 公共 capability | 继承的 `common`、`grilling`；自身的 `coding`、`productivity`、`frontend` | 与 Moluoxixi 相同的共享 skills、外部固定版本 skills 和 MCP servers |
 | 原生项目资产 | `.trellis/workflow.md`、`tasks/`、`spec/`、`scripts/`、`agents/`、宿主配置 | 保存 Plan/Execute/Finish 状态、任务工件、规范和 agent 定义 |
 | AIRules 项目扩展 | `.trellis/knowledge/`、知识 runtime、宿主 hook、`trellis-knowledge` | 自动发现 source 变化并维护双向可追踪知识关系 |
 
@@ -258,7 +303,7 @@ trellis --version
 | `common` | `hindsight-docs` | 查询 Hindsight API、部署和高级配置文档 |
 | `frontend` | `frontend-design` | 指导有明确视觉方向的前端设计与重塑 |
 | `productivity` | `grill-me` | 启动严格需求访谈 |
-| `productivity` | `grilling` | 压力测试计划、决策或设计 |
+| `grilling` | `grilling` | 从 `general` 继承，压力测试计划、决策或设计 |
 | `productivity` | `handoff` | 生成跨 agent 交接文档 |
 | `productivity` | `teach` | 进行可记录进度的跨会话教学 |
 | `productivity` | `to-questionnaire` | 把未决问题转成问卷 |
@@ -308,19 +353,22 @@ Plan 阶段创建并确认 PRD，复杂任务补齐 design/implement 后 `task.p
 
 共享 skills、MCP 清单和供应商声明按能力集中在 `capabilities/<能力>/`，例如 `capabilities/common/skills/`。每个能力目录是纯数据目录，只包含 `capability.yaml`、skills、MCP 清单和文档；Role 在 `role.yaml` 中选择 capability。运行时加载器位于 `scripts/lib/capabilities.ts`，负责按声明顺序组合 vendor，合并兼容投影、去重完全相同的 projection，并拒绝来源或目标冲突。目录结构与完整映射见 [capabilities/README.md](capabilities/README.md)。
 
+角色通过 `extends_roles` 递归继承父角色的 capabilities，再加入自身能力。共同祖先和重复能力自动去重；缺失父角色与循环继承会报错。父角色可作为纯声明模板；子角色使用自身的 role vendor、宿主和 CLI packages。规则见 [角色继承](capabilities/README.md#角色继承)。
+
 宿主目录、别名、skills 投影开关和 MCP 格式统一声明在 [hosts/hosts.yaml](hosts/hosts.yaml)。`scripts/lib/hosts.ts` 负责加载、校验和路径解析，声明类型放在 `scripts/lib/types/`。新增宿主只需更新 YAML；字段与维护说明见 [hosts/README.md](hosts/README.md)。
 
 分发链路为：
 
 ```text
 role manifest
+  -> 角色继承与 capabilities 合并
   -> 固定 vendor checkout / package setup
   -> vendor staging
   -> canonical ~/.agents/skills
   -> 宿主 skill 投影与 MCP 合并
 ```
 
-当前安装 role 的受管 shared layer 会替换上一 role 不再需要的受管链接，因此不要把三个 role 理解为完全隔离、永久叠加的环境。用户已有的同名 MCP 配置优先保留。`airules verify` 检查受管 skills、宿主 links 和 MCP server 名称，不检查项目初始化器生成的 agents/hooks；后者应通过角色工作流自身的检查完成。
+当前安装 role 的受管 shared layer 会替换上一 role 不再需要的受管链接，因此多个 role 共用同一个用户级环境。用户已有的同名 MCP 配置优先保留。`airules verify` 检查受管 skills、宿主 links 和 MCP server 名称，不检查项目初始化器生成的 agents/hooks；后者应通过角色工作流自身的检查完成。
 
 ## 开发
 

package/capabilities/README.md

@@ -24,6 +24,7 @@ capabilities/
 │   ├── capability.yaml         # Anthropic frontend-design 上游声明
 │   ├── mcps.json               # Playwright
 │   └── README.md
+├── grilling/capability.yaml    # 仅同步 Matt Pocock grilling
 ├── productivity/capability.yaml # Matt Pocock productivity 上游声明
 └── engineering/capability.yaml # Matt Pocock engineering 上游声明
 ```
@@ -41,25 +42,35 @@ AIRules 自有共享 skills 实际存放在 `capabilities/<能力>/skills/`。
 | [`frontend`](frontend/README.md) | Anthropic `frontend-design` | Playwright |
 | `productivity` | Matt Pocock productivity skills | 无 |
 | `engineering` | Matt Pocock engineering skills | 无 |
+| [`grilling`](grilling/README.md) | Matt Pocock `grilling` | 无 |
 
-| Role | Capabilities |
-|---|---|
-| `trellis` | `common`, `coding`, `productivity`, `frontend` |
-| `moluoxixi` | `common`, `coding`, `productivity`, `frontend` |
-| `matt` | `engineering`, `productivity` |
+| Role | 继承 | 自身 Capabilities |
+|---|---|---|
+| [`general`](../roles/general/README.md) | 无 | `common`, `grilling` |
+| `trellis` | `general` | `coding`, `productivity`, `frontend` |
+| `moluoxixi` | `general` | `coding`, `productivity`, `frontend` |
+| `matt` | `general` | `engineering`, `productivity` |
 
 角色选择示例：
 
 ```yaml
 # roles/<role>/role.yaml
+extends_roles: [general]
 capabilities:
-  - common
   - coding
   - frontend
 ```
 
 `roles/<role>/role.yaml` 声明角色自身的 `role_vendor`、CLI 安装命令、宿主支持、继承关系和 publishable packages。角色自有的 `init-project`、hooks、agents、packages 等仍放在 `roles/<role>/`，由 `role-assets` 全量同步。旧包若仍带有 `constants/skills.ts`，安装器会在没有 `role.yaml` 时兼容读取它。
 
+## 角色继承
+
+`extends_roles` 将角色作为可复用的能力模板。`general` 既能独立安装，也作为开发角色的基础：子角色安装时递归读取父角色的 `capabilities`，再加入自己的能力。多层和多父角色按声明顺序合并，共同祖先与相同能力只处理一次。子角色可用 `capabilities: []` 继承整组通用能力。
+
+继承范围是 capability 声明及其 skills、MCP 与供应商 setup。子角色的 `role_vendor`、角色专属资产、CLI packages 和 hosts 由自身声明；安装器将继承的第一方能力从子角色的 AIRules 远程 checkout 投影到 vendor。能力模板可只声明 `capabilities` 和 `extends_roles`；独立安装的角色需提供自身 `role_vendor`。
+
+缺失父角色、循环继承、单份声明中的重复能力及供应商版本冲突会报错。`grilling` 同时由父角色显式选择、由子角色的 `productivity` namespace 带入时，同一供应商的同一源码只投影一次；不同来源的同名 skill 仍报冲突。
+
 ## MCP 清单
 
 ```json

package/capabilities/common/README.md

@@ -10,7 +10,7 @@
 |---|---|
 | `create-skill` | 创建或修订可复用的 agent skill |
 | `spec-organization` | 整理项目规范文档、索引和链接 |
-| `hindsight-memory` | 通过 Hindsight MCP 回忆历史决定、保存已验证结果，并按项目区分 bank |
+| `hindsight-memory` | 通过 Hindsight MCP 回忆历史决定、保存已验证结果，并按项目区分 bank；连接官方记忆控制台 |
 
 上游 `hindsight-docs` skill 按固定 commit 远程同步，用于查询 Hindsight API、部署和高级配置。固定 commit 约束 skill 源码；服务运行包由部署环境单独管理。
 
@@ -23,7 +23,7 @@
 ```powershell
 $env:HINDSIGHT_API_LLM_PROVIDER = 'ollama'
 $env:HINDSIGHT_API_LLM_MODEL = 'llama3.2'
-uvx --from hindsight-api hindsight-local-mcp
+uvx --from hindsight-api==0.10.2 hindsight-local-mcp
 ```
 
 云模型使用 `HINDSIGHT_API_LLM_API_KEY` 和对应 provider/model 配置。首次启动会下载运行依赖和本地 embedding 模型，默认嵌入式数据库保存在 `~/.pg0/hindsight-mcp/`，重启后保留数据。AIRules 安装时写入连接配置，服务由部署环境启动和维护。
@@ -31,3 +31,15 @@ uvx --from hindsight-api hindsight-local-mcp
 默认 `/mcp/` 为多 bank 模式，工具调用通过 `bank_id` 指定项目。单 bank 可使用 `/mcp/<bank-id>/`；团队共享可连接已部署服务。通过宿主中的同名 `hindsight` 配置覆盖 `url`，AIRules 会保留用户配置；Codex 使用 `[mcp_servers.hindsight]` 的 `url`，OpenCode 使用 `type: "remote"`。
 
 连接后验证 `retain`、`recall` 和 `reflect` 是否可用，再保存一条测试事实，在新会话中检索它。完整运行参数见 [官方 Local MCP 文档](https://hindsight.vectorize.io/docs/integrations/local-mcp)。
+
+## 记忆可视化
+
+已有 Hindsight API 时，独立启动官方控制台，直接查看当前服务的记忆：
+
+```bash
+npx --yes @vectorize-io/hindsight-control-plane@0.10.2 --hostname 127.0.0.1 --port 9999 --api-url http://localhost:8888
+```
+
+打开 `http://localhost:9999`，选择 MCP 使用的同一 bank，查看记忆事实、来源文档、实体关系图和异步操作状态。远程服务使用对应的 API 根地址。
+
+首次部署可使用 `hindsight-memory` skill 自带的 [Compose](skills/hindsight-memory/assets/compose.yaml)，一次启动 API、MCP 和控制台，持久化到固定 Docker volume。部署资产会完整同步到 `~/.agents/skills/hindsight-memory/`；模型配置放在用户配置目录。两种方式的步骤、存储区别与验证方法见 [可视化操作说明](skills/hindsight-memory/references/visualization.md)。

package/capabilities/common/skills/hindsight-memory/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hindsight-memory
-description: Recall and retain project decisions, verified fixes, and user preferences through Hindsight MCP. Use when work depends on prior decisions, a completed task produces reusable learnings, or the user asks to remember or retrieve context across sessions.
+description: Recall and retain project decisions, verified fixes, and user preferences through Hindsight MCP. Use when work depends on prior decisions, a completed task produces reusable learnings, or the user asks to remember, retrieve, browse, or visualize memory across sessions.
 ---
 
 # Hindsight Memory
@@ -25,6 +25,14 @@ description: Recall and retain project decisions, verified fixes, and user prefe
 
 只记录已确认且有复用价值的内容。未验证的推测应明确标注状态；凭据和密钥留在配置系统中。已有同一结果时补充新信息，避免重复写入。若工具返回异步 operation，按工具能力检查状态，只有确认完成后才声称已保存。
 
+`grilling` 结束后，用户已确认的结论可按上述规则保存，并附上理由、取舍和下一步验证条件；待验证假设明确保留其状态。
+
+## 查看与可视化
+
+用户要求浏览记忆、查看实体关系图或部署可视化时，读取 [可视化操作说明](references/visualization.md)。先核对当前 MCP 的 API 地址与 bank，再连接官方 Hindsight 控制台。已有服务使用独立控制台接入同一个 API；首次部署使用随 skill 分发的 Compose 资产。
+
+在控制台选择上述同一 bank，查看记忆、来源文档和实体关系；只有页面能访问且测试记忆出现在对应 bank 时，才确认可视化连接成功。部署命令完成或页面可访问本身不能证明记忆读写已成功。
+
 ## 服务不可用
 
 MCP 工具缺失或连接失败时，说明记忆当前不可用，继续可以独立完成的开发工作。使用当前配置的服务恢复连接；不要另起 `hindsight-embed` CLI daemon 来替代 MCP，它可能使用不同数据库和 bank。需要上游 API、部署或高级配置细节时读取 `hindsight-docs` skill；服务安装说明见 [Hindsight Local MCP 官方文档](https://hindsight.vectorize.io/docs/integrations/local-mcp)。

package/capabilities/common/skills/hindsight-memory/assets/compose.yaml

@@ -0,0 +1,23 @@
+name: airules-hindsight
+
+services:
+  hindsight:
+    image: ghcr.io/vectorize-io/hindsight:0.10.2
+    restart: unless-stopped
+    shm_size: 1gb
+    ports:
+      - '127.0.0.1:8888:8888'
+      - '127.0.0.1:9999:9999'
+    environment:
+      HINDSIGHT_API_LLM_PROVIDER: ${HINDSIGHT_API_LLM_PROVIDER:?Set the LLM provider in hindsight.env}
+      HINDSIGHT_API_LLM_MODEL: ${HINDSIGHT_API_LLM_MODEL:?Set the LLM model in hindsight.env}
+      HINDSIGHT_API_LLM_API_KEY: ${HINDSIGHT_API_LLM_API_KEY:-}
+      HINDSIGHT_API_LLM_BASE_URL: ${HINDSIGHT_API_LLM_BASE_URL:-}
+      HINDSIGHT_API_WORKER_ID: airules-hindsight
+      HINDSIGHT_CP_DATAPLANE_API_URL: http://localhost:8888
+    volumes:
+      - memory-data:/home/hindsight/.pg0
+
+volumes:
+  memory-data:
+    name: airules-hindsight-data

package/capabilities/common/skills/hindsight-memory/assets/hindsight.env.example

@@ -0,0 +1,9 @@
+# Copy to ~/.config/airules/hindsight/hindsight.env and configure your model.
+HINDSIGHT_API_LLM_PROVIDER=openai
+HINDSIGHT_API_LLM_MODEL=gpt-4o-mini
+HINDSIGHT_API_LLM_API_KEY=
+
+# Optional API base URL for your provider. For Ollama running on the Docker
+# Desktop host, set provider=ollama, your installed model, and
+# HINDSIGHT_API_LLM_BASE_URL=http://host.docker.internal:11434/v1
+HINDSIGHT_API_LLM_BASE_URL=

package/capabilities/common/skills/hindsight-memory/references/visualization.md

@@ -0,0 +1,78 @@
+# 记忆可视化
+
+使用官方 Hindsight Control Plane，按 bank 浏览提取的事实、来源文档、实体关系图、mental models 和异步 operations。默认控制台为 `http://localhost:9999`，API 为 `http://localhost:8888`，MCP 为 `http://localhost:8888/mcp/`。
+
+先读取宿主当前 `hindsight` MCP 配置，确认 API 与 bank。多 bank endpoint `/mcp/` 的 API 根地址是移除 `/mcp/` 后的服务地址；单 bank endpoint `/mcp/<bank-id>/` 同样使用 API 根地址，控制台中选择对应 bank。经过反向代理的服务应使用部署方提供的 API 根地址。
+
+## 已有记忆服务：添加控制台
+
+`hindsight-local-mcp` 同时提供完整 API。保留正在使用的服务及其数据，只启动独立控制台并连接当前 API：
+
+```bash
+npx --yes @vectorize-io/hindsight-control-plane@0.10.2 --hostname 127.0.0.1 --port 9999 --api-url http://localhost:8888
+```
+
+在浏览器打开 `http://localhost:9999`，选择 MCP 使用的项目 bank。远程服务将 `--api-url` 替换为实际 API 地址，同时核对宿主 MCP 指向同一服务；服务鉴权配置见 [官方安装文档](https://hindsight.vectorize.io/developer/installation)。
+
+`hindsight-local-mcp` 的本地数据库默认位于 `~/.pg0/hindsight-mcp/`。独立控制台读写该 API 的现有数据库；下述 Docker 部署使用另一个存储卷，适用于首次部署。需要迁移已有库时先按上游数据库迁移文档处理。
+
+## 首次部署：API 与控制台一起启动
+
+前提：Docker Compose 可用、Docker daemon 已启动，并有可用的 LLM provider/model。部署资产位于本 skill 的 `assets/`，会完整分发到 `~/.agents/skills/hindsight-memory/`。镜像固定为 `0.10.2`，同时提供 API、MCP 和控制台。
+
+配置文件放在用户配置目录，避免 skill 更新覆盖模型设置。以下命令从已安装 skill 读取模板；在仓库内验证时，将 `hindsightSkill` 改为本文件上一级目录。
+
+### PowerShell
+
+```powershell
+$hindsightSkill = Join-Path $env:USERPROFILE '.agents/skills/hindsight-memory'
+$hindsightConfigDir = Join-Path $env:USERPROFILE '.config/airules/hindsight'
+$hindsightEnvFile = Join-Path $hindsightConfigDir 'hindsight.env'
+New-Item -ItemType Directory -Force $hindsightConfigDir | Out-Null
+if (-not (Test-Path -LiteralPath $hindsightEnvFile)) {
+    Copy-Item -LiteralPath "$hindsightSkill/assets/hindsight.env.example" -Destination $hindsightEnvFile
+}
+```
+
+编辑 `hindsight.env`，填写 provider、model 和该 provider 所需的 API key。配置就绪后：
+
+```powershell
+docker compose --env-file $hindsightEnvFile --file "$hindsightSkill/assets/compose.yaml" config --quiet
+docker compose --env-file $hindsightEnvFile --file "$hindsightSkill/assets/compose.yaml" up --detach
+docker compose --env-file $hindsightEnvFile --file "$hindsightSkill/assets/compose.yaml" logs --tail 60 hindsight
+```
+
+### macOS / Linux
+
+```bash
+hindsight_skill="$HOME/.agents/skills/hindsight-memory"
+hindsight_config_dir="$HOME/.config/airules/hindsight"
+hindsight_env_file="$hindsight_config_dir/hindsight.env"
+mkdir -p "$hindsight_config_dir"
+if [ ! -f "$hindsight_env_file" ]; then
+  cp "$hindsight_skill/assets/hindsight.env.example" "$hindsight_env_file"
+fi
+```
+
+编辑 `hindsight.env`，填写模型配置后：
+
+```bash
+docker compose --env-file "$hindsight_env_file" --file "$hindsight_skill/assets/compose.yaml" config --quiet
+docker compose --env-file "$hindsight_env_file" --file "$hindsight_skill/assets/compose.yaml" up --detach
+docker compose --env-file "$hindsight_env_file" --file "$hindsight_skill/assets/compose.yaml" logs --tail 60 hindsight
+```
+
+云模型填写 provider、model 和 API key；Ollama 可使用 `provider=ollama`、本地已安装的 model，以及 Hindsight 容器可访问的 `HINDSIGHT_API_LLM_BASE_URL`。Docker Desktop 的宿主 Ollama 地址通常为 `http://host.docker.internal:11434/v1`；Linux 使用实际可达的 OpenAI 兼容 API 地址。
+
+Compose 将 API 与控制台端口绑定到本机，API 与控制台连接同一数据库。记忆存入固定 named volume `airules-hindsight-data`；skill 路径变化、容器重启与重建后仍复用该卷。停止服务可将 `up --detach` 替换为 `stop`，启动时继续使用同一配置和卷。
+
+## 验证当前项目的记忆
+
+1. 确认 API 的 `/health` 和控制台可以访问，宿主发现 `retain`、`recall`、`reflect` 工具。
+2. 用 SKILL.md 的规则选定项目 bank。通过 MCP 保存一条用户同意的非敏感测试事实；异步写入等待 operation 完成。
+3. 在控制台选择同一 bank，确认事实及其来源可见；存在实体时查看实体关系图。若页面为空，先检查 API 地址、bank 与 operation 状态。
+4. 在新会话用 `recall` 检索同一事实。以上步骤成功后，才报告记忆读写与可视化已连接。
+
+部署问题读取日志，模型连接问题核对 provider/model/base URL；检查配置时使用 `config --quiet`，无需输出 API key。记忆为空时核对服务与 bank，避免启动另一个数据库实例。
+
+官方参考：[安装与控制台](https://hindsight.vectorize.io/developer/installation)、[MCP endpoints](https://hindsight.vectorize.io/developer/mcp-server)、[0.10.2 发布](https://github.com/vectorize-io/hindsight/releases/tag/v0.10.2)。

package/capabilities/grilling/README.md

@@ -0,0 +1,5 @@
+# Grilling
+
+[`capability.yaml`](capability.yaml) 从 Matt Pocock 的 skills 仓库固定版本同步 `skills/productivity/grilling`，提供计划、决策与假设审问能力。
+
+`grilling` capability 只投影这一项 skill。需要整组效率 skills 时可选择 `productivity`；需要轻量通用组合时使用 [`general`](../../roles/general/README.md)。

package/capabilities/grilling/capability.yaml

@@ -0,0 +1,12 @@
+schema_version: 1
+capability_id: grilling
+description: Matt Pocock's grilling skill for stress-testing plans and decisions.
+vendors:
+  - name: mattpocock
+    source: https://github.com/mattpocock/skills.git
+    revision: 8b78b531ab965735c5dc74f6f7a219e1e37326df
+    projections:
+      - kind: skills
+        source_base_dir: skills/productivity
+        skills:
+          - grilling

package/dist/scripts/lib/types/manifest.d.ts

@@ -75,3 +75,11 @@ export interface RoleContract {
     path: string;
     value: Record<string, unknown>;
 }
+export interface RoleContractData {
+    hosts?: unknown;
+    packages?: unknown;
+    capabilities?: unknown;
+    extendsRoles?: unknown;
+    roleVendor?: unknown;
+    roleVendorPosition?: 'before' | 'after';
+}

package/dist/scripts/lib/vendor-staging.js

@@ -234,10 +234,16 @@ function requireNoTargetConflicts(assets, label) {
     for (const asset of assets) {
         const previous = accepted.find(candidate => conflicts(candidate.target, asset.target));
         if (previous) {
+            // A skill selected by a base role can also be included in a child namespace.
+            if (previous.vendorId === asset.vendorId && previous.kind === asset.kind
+                && previous.source === asset.source && previous.target === asset.target) {
+                continue;
+            }
             throw new Error(`${label} at "${asset.target}": ${previous.vendorId} conflicts with ${asset.vendorId}`);
         }
         accepted.push(asset);
     }
+    return accepted;
 }
 function resolveRoleChild(roleRoot, relativePath, kind) {
     const requested = path.join(roleRoot, portablePath(relativePath));
@@ -281,8 +287,7 @@ function expandRoleAssets(roleRoot, vendorId) {
             });
         }
     }
-    requireNoTargetConflicts(roleAssets, 'Canonical role-assets target conflict');
-    return roleAssets;
+    return requireNoTargetConflicts(roleAssets, 'Canonical role-assets target conflict');
 }
 function buildStagingPlan(manifest, homeDir, role) {
     const ordinary = [];
@@ -296,13 +301,13 @@ function buildStagingPlan(manifest, homeDir, role) {
             ordinary.push(...expandOrdinaryLink(homeDir, vendorId, link));
         }
     }
-    requireNoTargetConflicts(ordinary, 'Ordinary vendor target conflict');
+    const uniqueOrdinary = requireNoTargetConflicts(ordinary, 'Ordinary vendor target conflict');
     if (roleDeclarations.length > 1) {
         throw new Error('A vendor manifest may declare at most one canonical role-assets source');
     }
     const roleDeclaration = roleDeclarations[0];
     return {
-        ordinary,
+        ordinary: uniqueOrdinary,
         roleSource: roleDeclaration === undefined
             ? undefined
             : resolveRoleSource(homeDir, role, roleDeclaration.vendorId, roleDeclaration.source),

package/dist/scripts/lib/vendors.js

@@ -4,6 +4,7 @@ import { fileURLToPath, pathToFileURL, URL } from 'node:url';
 import { parseDocument } from 'yaml';
 import { CAPABILITY_NAMES, composeCapabilities } from './capabilities.js';
 import { HOST_IDS } from './hosts.js';
+import { resolveRoleManifestPath, roleOverlayOrder } from './roles.js';
 import { flattenedSkillName, flattenedVendorSkillTarget } from './skill-projection.js';
 const vendorNamePattern = /^[A-Za-z0-9][\w-]*$/u;
 const npmPackageNamePattern = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/u;
@@ -216,7 +217,7 @@ export async function loadVendorManifest(manifestPath) {
         ?? module.default?.roleVendor;
     const vendorTree = roleVendor === undefined
         ? (isRoleYaml ? {} : module.vendors ?? module.default?.vendors ?? module.default)
-        : composeRoleVendorTree(manifestPath, roleVendor, roleContract);
+        : await composeRoleVendorTree(manifestPath, roleVendor, roleContract);
     if (!vendorTree || typeof vendorTree !== 'object') {
         throw new Error(`Vendor manifest "${manifestPath}" must export a "vendors" object or a "roleVendor" definition`);
     }
@@ -299,6 +300,9 @@ function tryLoadRoleContract(manifestPath) {
     }
     return {
         ...(capabilities === undefined ? {} : { capabilities }),
+        ...(record.extends_roles === undefined && record.extendsRoles === undefined
+            ? {}
+            : { extendsRoles: record.extends_roles ?? record.extendsRoles }),
         ...(record.hosts === undefined ? {} : { hosts: record.hosts }),
         ...(record.packages === undefined ? {} : { packages: record.packages }),
         ...(record.role_vendor === undefined && record.roleVendor === undefined
@@ -307,24 +311,45 @@ function tryLoadRoleContract(manifestPath) {
         ...(roleVendorPosition === undefined ? {} : { roleVendorPosition }),
     };
 }
-function requireRoleCapabilityContract(manifestPath, contract) {
-    const capabilities = contract.capabilities;
+async function requireRoleCapabilityContract(manifestPath, contract) {
     const contractPath = resolveRoleContractPath(manifestPath);
-    if (!Array.isArray(capabilities) || capabilities.length === 0) {
-        throw new Error(`Role contract "${contractPath}" must declare a non-empty "capabilities" list`);
+    const extendsRoles = contract.extendsRoles ?? [];
+    if (!Array.isArray(extendsRoles) || !extendsRoles.every(role => typeof role === 'string')) {
+        throw new TypeError(`Role contract "${contractPath}" field "extends_roles" must be a string array`);
     }
+    const roleRoot = path.dirname(contractPath);
+    const repoRoot = path.resolve(roleRoot, '..', '..');
+    const role = path.basename(roleRoot);
+    const lineage = extendsRoles.length === 0 ? [role] : await roleOverlayOrder(repoRoot, role);
+    const capabilities = [];
     const seen = new Set();
-    for (const capability of capabilities) {
-        if (typeof capability !== 'string' || !CAPABILITY_NAMES.includes(capability)) {
-            throw new Error(`Role contract "${contractPath}" references unknown capability "${String(capability)}"`);
+    for (const ancestor of lineage) {
+        const ancestorPath = ancestor === role ? contractPath : resolveRoleManifestPath(repoRoot, ancestor);
+        const ancestorContract = ancestor === role ? contract : tryLoadRoleContract(ancestorPath);
+        const declared = ancestorContract?.capabilities ?? [];
+        if (!Array.isArray(declared)) {
+            throw new TypeError(`Role contract "${ancestorPath}" must declare "capabilities" as a list`);
         }
-        if (seen.has(capability)) {
-            throw new Error(`Role contract "${contractPath}" declares duplicate capability "${capability}"`);
+        const localSeen = new Set();
+        for (const capability of declared) {
+            if (typeof capability !== 'string' || !CAPABILITY_NAMES.includes(capability)) {
+                throw new Error(`Role contract "${ancestorPath}" references unknown capability "${String(capability)}"`);
+            }
+            if (localSeen.has(capability)) {
+                throw new Error(`Role contract "${ancestorPath}" declares duplicate capability "${capability}"`);
+            }
+            localSeen.add(capability);
+            if (!seen.has(capability)) {
+                capabilities.push(capability);
+                seen.add(capability);
+            }
         }
-        seen.add(capability);
+    }
+    if (capabilities.length === 0) {
+        throw new Error(`Role contract "${contractPath}" must declare a non-empty "capabilities" list, directly or through inheritance`);
     }
     return {
-        capabilities: capabilities,
+        capabilities,
         ...(contract.roleVendorPosition === undefined ? {} : { roleVendorPosition: contract.roleVendorPosition }),
     };
 }
@@ -448,11 +473,11 @@ function normalizeVendorDefinition(value, manifestPath) {
 /**
  * 依据 role.yaml 声明的 capabilities，把清单导出的 roleVendor 组合成完整 vendors 列表。
  */
-function composeRoleVendorTree(manifestPath, roleVendor, roleContract) {
+async function composeRoleVendorTree(manifestPath, roleVendor, roleContract) {
     if (!isVendorEntry(roleVendor)) {
         throw new Error(`Vendor manifest "${manifestPath}" export "roleVendor" must be a vendor definition with name and source`);
     }
-    const contract = requireRoleCapabilityContract(manifestPath, roleContract ?? tryLoadRoleContract(manifestPath) ?? {});
+    const contract = await requireRoleCapabilityContract(manifestPath, roleContract ?? tryLoadRoleContract(manifestPath) ?? {});
     return composeCapabilities(contract.capabilities, {
         roleVendor: normalizeVendorDefinition(roleVendor, manifestPath),
         ...(contract.roleVendorPosition === undefined ? {} : { roleVendorPosition: contract.roleVendorPosition }),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "moluoxixi-ai-rules",
   "type": "module",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "Remote AI role asset distribution for supported hosts.",
   "license": "MIT",
   "repository": "https://github.com/moluoxixi/AIRules",

package/roles/general/README.md

@@ -0,0 +1,48 @@
+# General
+
+`general` 提供计划审问、长期记忆、skill 编写和知识整理等通用能力。角色在 [`role.yaml`](role.yaml) 中选择 `common` 和 `grilling`，资产从远程供应商同步。
+
+## 安装
+
+```bash
+npm install --global moluoxixi-ai-rules
+airules install general --host all
+airules verify general --host all
+```
+
+安装后可在宿主中直接使用以下能力：
+
+| Skill | 用途 |
+|---|---|
+| `grilling` | 逐项审问计划、决策和假设，明确取舍与验证条件 |
+| `hindsight-memory` | 按项目回忆和保存已确认的信息，查看记忆控制台 |
+| `hindsight-docs` | 查询 Hindsight API、部署和高级配置 |
+| `create-skill` | 编写或修订通用 skill |
+| `spec-organization` | 整理文档目录、索引和链接 |
+
+唯一 MCP 是 Hindsight，默认地址为 `http://localhost:8888/mcp/`。安装器分发连接配置和可视化部署资产，运行记忆服务需要配置模型。
+
+## 使用
+
+```text
+请用 grilling 审问这个计划，逐项检查假设和取舍。
+请记住我们已确认的结论、理由和下一步验证条件。
+回忆这个项目之前的决定，并核对是否仍适用。
+打开当前项目的记忆可视化，查看保存的事实和实体关系图。
+```
+
+记忆控制台默认位于 `http://localhost:9999`。在控制台选择与 MCP 相同的项目 bank，查看事实、来源文档、实体关系图和异步操作状态。已有 Hindsight API 时只需添加控制台；首次部署可使用随 `hindsight-memory` skill 分发的 Docker Compose。操作步骤见 [记忆可视化](../../capabilities/common/skills/hindsight-memory/references/visualization.md)。
+
+审问中的候选方案与已确认结论分别标注状态；只有确认保存成功后才报告记忆已写入。
+
+## 作为基础角色
+
+`moluoxixi`、`trellis` 和 `matt` 通过 `extends_roles: [general]` 继承通用能力。新增开发角色同样可以继承，再选择自身能力：
+
+```yaml
+extends_roles: [general]
+capabilities:
+  - coding
+```
+
+多层继承与共同祖先自动合并；规则见 [角色继承](../../capabilities/README.md#角色继承)。

package/roles/general/role.yaml

@@ -0,0 +1,21 @@
+schema_version: 1
+role_id: general
+role_version: 0.1.0
+status: stable
+canonical_root: roles/general
+description: Shared skills for grilling plans, organizing knowledge, and persistent memory with the Hindsight console.
+capabilities:
+  - common
+  - grilling
+hosts: all
+extends_roles: []
+role_vendor:
+  name: general-role
+  source: https://github.com/moluoxixi/AIRules.git
+  projections:
+    - kind: role-assets
+      source_dir: roles/general
+distribution:
+  bootstrap_manifest: role.yaml
+  full_role_path_required: true
+  npm_embedded_source: false

package/roles/matt/role.yaml

@@ -11,7 +11,7 @@ capabilities:
   - productivity
 role_vendor_position: after
 hosts: all
-extends_roles: []
+extends_roles: [general]
 role_vendor:
   name: matt-role
   source: https://github.com/moluoxixi/AIRules.git

package/roles/moluoxixi/role.yaml

@@ -9,12 +9,11 @@ assets:
   mcp: mcp
   packages: packages
 capabilities:
-  - common
   - coding
   - productivity
   - frontend
 hosts: all
-extends_roles: []
+extends_roles: [general]
 role_vendor:
   name: moluoxixi
   source: https://github.com/moluoxixi/AIRules.git

package/roles/trellis/role.yaml

@@ -8,12 +8,11 @@ assets:
   skills: skills
   mcp: mcp
 capabilities:
-  - common
   - coding
   - productivity
   - frontend
 hosts: all
-extends_roles: []
+extends_roles: [general]
 role_vendor:
   name: trellis
   source: https://github.com/moluoxixi/AIRules.git