buildr

Files (7)

• SKILL.md
• agent-operations.md · references/
• asset-maintenance.md · references/
• code-observation.md · references/
• external-connections.md · references/
• local-services.md · references/
• runtime.md · references/

SKILL.md (first lines)

# Buildr Skill

Buildr 治理组织工作资产并投射到智能体运行时（Agent runtime）。工作事实说明“做什么”，工作方法说明“怎么做”；源资产、当前诊断和实际命令是依据，运行时（Runtime）是可重建入口。Buildr 通过已接入智能体（Agent）交付明确功能结果，理解和推理仍由智能体（Agent）承担，不保存本机版本偏好。

Agent 是 Buildr 功能的默认操作入口。在用户目标和已有授权内直接执行并验证；只在缺少业务决定或授权时询问。用户选择手动操作，或当前工具、权限、登录态不支持时，再提供准确手动入口。

## 执行与按需读取

1. 确认目标工作空间（Workspace）；未指定时从当前目录定位组织根，`--target` 不指向服务（Service）代码仓。
   支持按归属选版的 npm 默认 `buildr` 会在业务命令解析前，按 `--target` 或当前目录所属工作空间（Workspace）的既有网页管理登记，自动选择发布版或开发版；不要求网页运行。普通工作继续使用 `buildr`，不保存另一份版本偏好，不手改管理记录或默认链接。子目录和工作树（Worktree）仅用于定位归属，具体命令的目标参数仍遵循自身帮助。`version --json` 报告所选实际版本；`update`、`installation status`、`web launcher` 等安装自身动作保持当前 npm 安装，显式开发入口和图形启动器（Launcher）保持绑定来源。旧 npm 入口需先升级才具备选择能力；所选来源不可用或归属冲突时按明确诊断恢复，不切换另一版绕过。
2. `<agent>` 使用当前宿主的明确身份；用户指定其他运行时（Runtime）时遵从其选择。不得从技能路径、生成标记或 Doctor 检测结果推断宿主。身份未知可省略；`codex`、`dsh` 及未登记的有效品牌采用 `agents-standard`，已知专用例外保留。按需用 `buildr runtime list --json` 核对文件约定，而非等待品牌登记。显式 `--adapter` 必须存在；执行失败不借用其他适配器（Adapter）。
3. 已初始化且本次维护规则、技能等受管工作资产需要现状时，运行一次 `buildr doctor --agent <agent> --target <dir> --json`；已有同一现场的诊断直接复用。首次初始化按下表办理，不先制造缺失诊断。连接管理与数据库查询直接使用下表对应入口，不以 Doctor 为前置条件。
4. 选择下表对应动作；采用内部流程、调整工作方式、修改或替换 Skill 行为时，先加载 `capability-adaptation` 判断是否触达或产生跨 Skill 稳定依赖边界。
5. 受管工作资产写入后消费最新 Doctor 结果：完整 `init`、`sync`、组件（Component）安装或卸载已包含最终诊断；其他此类资产写入后再运行 Doctor。连接配置按对应入口核对保存与实际连接，不额外运行 Doctor。只有诊断指向专项问题或用户要求细查时追加 `commands check` 或 `runtime check`。文件准备成功不证明宿主安装、发现或当前会话激活已经验证。

| 当前目标 | 读取与动作 |
|---|---|
| 安装、检查或更新 Buildr | [安装与更新](references/asset-maintenance.md#安装与更新)；不猜目标工作空间（Workspace） |
| 在 Buildr 内使用 Codex、DSH、Qoder 对话，或配置内部对话账号 | [内部对话接入](references/agent-operations.md#内部对话与持续执行)；使用全局“对话”的独立账号与配置，先核对当前状态和真实程序，不复制桌面凭据 |
| 初始化工作空间（Workspace） | `buildr init --agent <agent> --target <dir> --name <name> --profile <personal\|team\|company>`；普通初始化默认登记到当前产品的本机 Buildr Web，随后完整准备标准或唯一既有方式并使用内置最终 Doctor；身份未知可省略 `--agent`。仅源资产使用 `init --source-only`，该模式不登记本机列表。登记不等于网页已打开；首次使用交接见 [资产维护](references/asset-maintenance.md#workspace--organization-root) |
| 更新或同步工作空间（Workspace），或处理检出内容变化 | [工作空间更新与检出变化](references/asset-maintenance.md#工作空间更新与检出变化) |
| 项目（Project）、服务（Service）、代码库实例（Repository Instance）、规则（Rule）、技能（Skill）、命令（Command）、组件（Component）或内置能力（Builtin）维护 | 按对象读取 [资产维护](references/asset-maintenance.md) 中对应小节；涉及组件（Component）成员时先核对整体所有权 |
| 投射、发现或适配器（Adapter）问题 | 读取 [运行时维护](references/runtime.md)；只检查当前目标运行时（Runtime） |
| 查看任务、测试或交付事实 | 下方专业入口；只读查看不创建记录，也不补造过去历史 |
| 查看全部代码库改动、提交历史及对应文件 | [只读代码观察](references/code-observation.md)；按登记实例、比较层与真实版本查看，网页与命令行接口（CLI）共享应用 |
| 启动、查看或停止本地服务，使用任务代码或主工作库做本地验证 | [服务本地运行](references/local-services.md)；按真实目录选择单个或多个服务，前端单选本地后端或远程测试环境，就绪后继续真实业务验证 |
| 任务需要外部系统信息，或管理外部系统连接（Connection） | [外部系统连接](references/external-connections.md)；按实际实例来源发现精确绑定及专业技能（Skill），使用 `buildr connection-skill --help`，专业参数以所选程序帮助为准 |
| 制作组织自有的外部系统接入 | 加载 `connection-authoring`，在 `skills/connections/<skill-id>/` 交付完整技能源、声明及必要程序，复用已有登记和投射；不预定义公司专业命令 |
| 授权开始或继续持久修改 | `task-triage` 分流并由 `task-manager` 在首次文件写入前登记或接续任务 |

## 专业入口
Agent runtime 先根据 Skill description 和用户目标发现入口 Skill。本 Skill 只有在 Buildr 管理意图与自身 description 匹配后才会被加载；它不是所有用户意图之前的全局 dispatcher，也不拦截 prompt。“收尾”等专业意图通常由 Agent 直接命中对应入口 Skill，再由该 Skill 读取自身的受管 capability bindings。

本 Skill 已加载后，只对下面明确列出的 Buildr 管理意图按需解析对应 capability。需要可替换 provider 时，在已初始化 workspace 运行当前 Agent Doctor 的 full detail，读取当前 scope 的 `capabilities` graph，再定位该项 contract 和 selected provider；不要把整张 consumer graph 当成本 Skill 的依赖表。`ready` 只表示结构可路由。调用 provider 前读取 contract 和 provider；不得根据 Skill id、description 或安装顺序猜测 conformance，也不需要 capability dispatch 命令。


| 用户意图 | 资产类型 |
|---|---|
| 查看待办/正式Task、Parent/Child、复盘文档状态与各专业当前状态 | `buildr.task-record/v4`及Review、Verification公开read model；复盘正文从`.buildr/local/task-retrospectives/<task-id>.md`读取 |
| 启动或继续已有active Formal Task | `buildr task inspect <task-id> --json`核对目标与scope；Agent再按真实Git/文件现场选择直接工作或matching Worktree |
| 查看 Parent/Child 关系、旧 Parent Plan 与整体完成观察 | `task parent inspect`；关系和终态由 Task Record 管理，旧 Parent Plan 只读 |
| 按需生成或查看已结束Task的执行效率复盘 | `task-retrospective`纯Skill基于当前可见事实写本机Markdown；Task Record v4的复盘字段只登记文档摘要和人的决定状态 |
| 建设或维护项目测试、四类边界、稳定入口及 `verification.yml` 测试登记 | `project-testing` 技能（Skill），同时维护测试登记与稳定入口 |
| 按任意用户请求或任务目标选择并执行检查，交付证据，或记录与查看已有任务验证报告 | `buildr.task-verification/v4` selected provider；Agent直接调用项目测试工具 |
| 显式创建、检查或清理 Task 的 Git worktree/provider evidence | `buildr.git-worktree-provider/v1` selected provider |
| 从 proposal、方案或直接实现开始完成开发工作 | 首次交付文件写入前使用 `task-triage` 与 `task-manager` 登记或接续任务；Agent 直接组合专业工具，不创建研发回执 |
| 用户要求“收尾”“交付”或完成当前工作 | `task-finish` 技能依据真实现场组合 Git、系统工具和已有 Buildr 接口；有任务则登记真实结果，无任务不创建，不要求旧候选或交接链 |
| 已明确 repository/ref 的 commit、push、commit+push 或其他已选 Git Operation | `buildr.git-operations/v1` selected provider；本 Skill 或直接用户继续决定 operation、目标与顺序 |

产品入口 Buildr Skill 只对自身已命中的 Buildr 管理意图执行内部能力路由；顶层 capability 的 binding 只选择 provider，不自动产生 Agent 意图命中。单项 capability blocked 不得阻塞 init、doctor、Project/Service 或其他无关动作。

正式任务（Formal Task）不是编辑、构建或有界测试的通用许可。已授权的持久交付默认先登记或接续任务以保留当前工作事实；纯只读不创建，收尾不补造历史。用户授权、实际仓库、引用和内容归属明确时按对应技能（Skill）继续工作；需要隔离时使用 `worktree create|inspect` 返回的真实工作目录。准备、代码生成和测试由项目（Project）或服务（Service）的实际工具负责。收尾由 `task-finish` 组合既有能力，本入口不复制流程。

## 完成

报告实际修改、验证、投射范围与遗留。复用当前动作已返回的诊断，不重复执行；存在相关错误时不能宣称该动作完成。仅将本次目标要求的长期信息写回对应源资产。

产品入口未被发现或投射损坏时，按[运行时维护](references/runtime.md#入口恢复)定位问题；当前离线参数以命令帮助为准。

From BuildrAI/Buildr, MIT.

More from BuildrAI/Buildr