quickforge: Instructions file for Codex

项目指令

• 修改代码后，使用相关测试、构建、lint 或针对性命令进行验证。
• 默认验证命令是 npm run test、npm run lint 和 npm run build；小改动可优先使用针对性检查。
• 除非用户明确要求，不要创建 Git commit、tag、push 到远端或发布 npm 包。
• 当用户说“发布一个小版本” / “发一个小版本” / “小版本发布”时，遵循 docs/architecture/patch-release-runbook.zh-CN.md：提升 patch 版本，更新发布文档，运行 test/lint/build，生成 runtime/offline 包，创建 Git commit/tag/push，最后提供 npm publish 命令；默认不要直接发布 npm。

Subagent 协作

• 实现非平凡需求时，优先使用 explore subagent 做只读仓库调研，包括定位入口、调用链、相关测试、文档/wiki 和影响面。
• 对复杂多步骤任务，可将边界清晰的子任务委托给合适的 subagent 分工推进；父 Agent 仍负责最终方案、最小化修改、结果整合和验证。
• subagent 不应绕过项目约束、审批边界或安全边界；涉及文件修改、命令执行、发布、Git 操作时仍遵循本文件现有规则。
• 简单、局部且已知文件的小改动可直接处理，无需为了形式化而调用 subagent。

项目约束

• 将 dist/、package-dist/、package-offline/ 视为生成产物；除非任务明确要求更新打包产物，否则不要手工修改这些目录。
• 不要新增或升级依赖，除非确有必要并说明理由；依赖变更时必须保持 package-lock.json 一致。
• 优先使用 npm scripts 和跨平台命令；除非任务明确指定平台，否则不要假设只能使用 Unix shell。
• 涉及 UI、样式或交互改动时，先遵循 DESIGN_LANGUAGE.md，不要随意引入新的视觉模式。
• 如果变更影响架构、模块职责、公共入口或发布流程，应同步更新相关 docs/wiki 文档；如果无需更新文档，需要说明原因。

代码 Wiki

• 项目代码 Wiki 位于 docs/wiki/README.md。
• 在理解模块、定位入口、进行较大变更或新人接手类任务时，优先读取 docs/wiki/README.md，再按需读取对应子目录文档。
• Wiki 仅作为导航和背景资料，最终判断以源码、配置和测试结果为准。

Startup Workflow

• 新会话开始先读取 docs/wiki/README.md、feature_list.json、progress.md、session-handoff.md，恢复上下文。
• 从 feature_list.json 选择当前 feature（非 done 且依赖已满足的优先）；本次会话只推进该 feature。
• 开始或恢复关键工作前，可用 bash init.sh 执行基线验证（npm run test、npm run lint、npm run build，不安装依赖）。

Verification Commands

• 修改代码后先做针对性检查（相关测试、lint、类型检查等）；小改动无需跑全套。
• 发布（release）前必须完整运行 npm run test、npm run lint、npm run build，全部通过才算完成；任何一项失败先修复，禁止在失败状态下继续发布流程。

One Feature at a Time / Stay in Scope

• 一次只处理当前 feature，不要顺带重构无关代码或修复无关问题。
• 发现与当前 feature 无关的问题，记入 progress.md 的 Notes，不扩大改动范围。
• 每个改动保持最小、聚焦，改动后同步更新 feature_list.json / progress.md。

Definition of Done

• 相关测试及与改动匹配的 lint/build/针对性检查通过；发布相关改动必须完整运行 npm run test、npm run lint、npm run build。
• 文档/wiki 已按需同步；未触碰生成产物（dist/、package-dist/、package-offline/）。
• feature_list.json、progress.md、session-handoff.md 已更新。