consensus-rnd: Instructions file for Claude Code

consensus-rnd - Agent 工作指南

本文件给在本仓库内维护 skill、清单和文档的 agent 使用，不是下游 host 的运行时配置。仓库定位与共识引擎设计哲学见英文 canonical README.md，中文 companion 见 README.zh-CN.md。

旁路推理通道: NyxID oracle (ChatGPT Pro)

NyxID oracle 可作为 codex / Claude 之外的独立推理通道，只走 oracle broker(nyxid proxy request oracle ... 的流式 OpenAI 兼容接口)；旧 nyxid oracle CLI 不得使用。单次提问一律通过 skills/sshx/scripts/run-oracle-worker.py，其能力检查、请求构造、流式拼装、完成判定和禁用路由以 skills/sshx/ORACLE_WORKER_SPEC.md 为唯一事实源，不另行加载 oracle-broker skill。多轮只用于旁路通道(sshx 席位不用)：broker 首轮带 "metadata": {"conversation_id": "new"}，后续带回返回的 conv_...。异步请求只在完成后读取一次结果，不 busy-loop 轮询。prompt 所需内容一律 inline。

仓库性质

这是一个跨平台 Agent Skills 发布仓库，不是应用代码仓库。唯一产物是 skills/<name>/ 下的 SKILL.md 及其配套文件，同一份 skills/ 由 Claude Code / Codex / Cursor / Gemini 共享。

目录约定

.
├── .claude-plugin/        # Claude Code 清单与 marketplace
├── .codex-plugin/         # Codex 清单
│   └── skills -> ../skills
├── .cursor-plugin/        # Cursor 清单
├── .gitattributes
├── .github/
│   ├── scripts/           # 版本同步工具
│   ├── tests/             # 仓库级文档一致性检查
│   └── workflows/         # CI
├── .gitignore
├── .version-bump.json     # 版本同步映射
├── AGENTS.md -> CLAUDE.md # 跨 agent 约定
├── CLAUDE.md              # 仓库规则
├── CONTRIBUTING.md        # 贡献指南
├── GEMINI.md              # Gemini 上下文入口
├── LICENSE
├── README.md              # 英文公开文档
├── README.zh-CN.md        # 中文公开文档
├── gemini-extension.json  # Gemini 扩展清单
├── package.json           # 包元数据
└── skills/
    └── sshx/             # 发布的共识 skill
        ├── CODEX_WORKER_SPEC.md
        ├── ORACLE_WORKER_SPEC.md
        ├── SKILL.md
        ├── formal/       # Lean 模型
        ├── scripts/      # Worker 机械实现
        └── tests/        # Skill 合同与行为验证

设计哲学(跨 skill 不动点)

• 单一主干、插件扩展：每个 skill 只有一条权威主链路，新能力挂载在明确的子模块或脚本上。
• 内核最小化：SKILL.md 承载触发条件、稳定不变量、行为合同和事实源索引；机械部分下沉到 scripts/，prompt 模板下沉到 prompts/。
• 边界清晰、职责分层：本文件承载仓库级边界；skill 的工作流细则和术语归其自身事实源维护。
• 事实源唯一：版本号以 .version-bump.json 为准，skill 行为以对应 SKILL.md 和测试为准，host 事实由 host 配置注入。
• 抽象优先、行为契约：跨 skill 只通过稳定文件 artifact、host 配置等边界协作，不耦合内部实现。
• 强类型边界、窄扩展点：扩展点必须有清楚职责、最小权限和可验证的授权来源，不引入通用生命周期权力。
• 抽象一旦能被滥用即设计未完成；删除优先，废弃路径直接移除，不保留兼容空壳或历史副本。
• 变更必须可验证：优先用 behavior test 或端到端可观察输入 / 输出 / 副作用断言；source-regression 只锁跨 artifact 一致性、事实源唯一性和授权边界。
• 治理前置：架构性或流程性规则必须和机械验证手段同时进入仓库。
• 正确架构优先：随着 skill 增长若边界自然变松，应重设计而非增加 escape hatch。
• 命名跟随职责：被脚本解析或跨 agent 传递的名字由所属事实源声明格式、canonical write policy 和迁移策略。
• 哲学文档不写 schema/identifier 版本后缀；Release semver 只作为 .version-bump.json 的发布坐标。