Imported from LandingStar/vibe-coding-guide (AGENTS.md). Install upstream with npx skills add LandingStar/vibe-coding-guide. Copyright stays with the author.

AGENTS

Local Work Trajectory

• Task-like implementation, validation, review, and write-back work must be reflected in Local Work Trajectory by the agent, not by the user.
• Before substantial task work begins, judge whether the task is large enough or split-worthy enough to need distinct Local Work lanes. If yes or uncertain, follow design_docs/tooling/local-work-lane-splitting/README.md; keep detailed lane split criteria there, not in this file.
• Leader-worker is the recommended execution structure for single-lane Local Work and the required structure for Local Work with two or more lanes. In multi-lane work, lane workers may be inactive while waiting for dependencies, review, or leader messages; the leader may also be inactive while waiting for worker feedback. Treat message-driven reactivation and mailbox/history audit as part of the orchestration contract, not as optional chat bookkeeping.
• Direct localTrajectory mutation is leader/main/supervisor authority. Bounded workers/subagents must not call localTrajectory directly; they must put trajectory/status suggestions in their Subagent Report.trajectory_update, and the leader/main agent consumes the report before mutating Local Work Trajectory. Worker report procedure: docs/worker-trajectory-update-reporting.md.
• When MCP exposes localTrajectory to a leader/main/supervisor, use it proactively: start when beginning a tracked task with no active trajectory, append for meaningful milestones, advance when the active milestone is complete, addLane as soon as a distinct work context begins, merge only for explicit fan-in, and relate only for visible relation metadata.
• When calling localTrajectory start, include sourceGraphId and sourceNodeId if a visible owning progress-map node is known so the trajectory is attached from birth. Use localTrajectory setAnchor when the current trajectory should move later; pass both sourceGraphId and sourceNodeId, or pass neither to clear the anchor. Prefer visible current-phase, active-slice, or planning-gate nodes over leaving task work unanchored.
• Use localTrajectory addCompound when a planned phase should appear as one large event with its own child trajectory; it does not pack or move existing events.
• Use localTrajectory packRange only to pack an existing continuous same-lane event interval into one compound event while preserving the interval in the child trajectory.
• Use localTrajectory appendChild, advanceChild, and closeChild to continue or finish the child trajectory of an existing compound parent.
• Do not wait for a user instruction such as "start trajectory"; do not ask the user to manually create trajectory nodes.
• If localTrajectory is expected but unavailable, report the MCP/tool exposure problem explicitly. Use the repository-local trajectory API only when the current project rules allow local file mutation.
• MCP path or host-environment configuration checks are not project work and must not be recorded into Local Work Trajectory unless the user explicitly says to track that environment task.

本项目默认采用基于文档闭环的开发流程。

开始工作前，先读：

1. design_docs/Project Master Checklist.md（短热状态入口）
2. Checklist 的 Current Recovery Read Order 指向的最新 closure/gate/review 文档
3. design_docs/Global Phase Map and Current Position.md
4. 当前 active planning 或 phase 文档
5. docs/starter-surface.md、docs/README.md 与当前任务直接相关的 docs/ 权威文档
6. 相关的 design_docs/tooling/ 长期协议

.codex/checkpoints/latest.md 与 .codex/handoffs/CURRENT.md 是恢复安全停点或停放分支的辅助入口；只有当 Checklist 指向它们、用户要求恢复对应分支，或需要核对 safe-stop/handoff footprint 时才默认读取。不要让旧 checkpoint/handoff 覆盖 Checklist 中更新的当前焦点。

design_docs/history/Project Master Checklist Archive 2026-06-22.md 是长历史归档，不是默认首读文件；只有追溯历史、审计旧 validation 或恢复旧阶段时才按需读取。

当前仓库的特殊点：

• 根目录 docs/ 是平台与官方实例定位的高层权威来源
• design_docs/ 主要承载状态板、planning/phase 文档与内部设计推导
• 若两者冲突，以 docs/ 为准

当前目标宿主支持定位：

• 当前目标明确支持 Codex；Codex 主链是 AGENTS.md + MCP + CLI/validation，不是历史兼容路径或次要路径。
• VS Code / Copilot extension 是同一平台后端上的 Host UX Layer 实现；它不替代 Codex 主链，也不应让规则弱化 Codex 支持。
• 需要接入 Codex 能力时，优先检查 Codex 实际入口：AGENTS.md、.codex/config.toml 或 codex mcp add、以及 src/mcp/server.py 暴露的工具。
• .vscode/mcp.json 只覆盖 VS Code / Copilot Chat 注册面；不能据此判断 Codex 已加载 MCP。
• 后端/运行时默认应保持宿主无关；若 Codex 与 Copilot 的差异只是实际应用入口不同，优先在 Interaction Adapter 或 Host UX 的薄组件处理，不要改写 Portable Runtime / Core Contract。
• 当 MCP 暴露 workspaceDbcCommand 时，将其视为每个 agent 自己的工作区级 DBC 命令中转；需要 CLI 等价的 DBC 操作时优先调用该 relay 或专用结构化 MCP 工具，不要自行解析全局 doc-based-coding、venv 或 checkout 路径。

执行规则：

• 在没有窄 scope 文档前，不进入大规模实现。
• 代码、测试、帮助和文档更新必须对应同一个当前切片。
• 若发现新问题超出当前切片，先写回 planning-gate，而不是就地扩 scope。
• 通过 Codex/Qoder/opencode 等后端 runtime 执行 worker 时，应优先走带 compact runtime invocation audit 的 host-owned wrapper；中断、超时、retryable failure、最终失败或恢复成功都应留下可审计记录，且不得保存 raw transcript 或 secret value。
• 只有在安全停点才刷新 .codex/handoffs/CURRENT.md。
• 安全停点下，允许 model 主动进入 handoff 分支；handoff 分支内只有 blocked 是自动停止信号。
• 命中重要设计节点时，先整理设计结论交用户审核，再继续下一大步。
• 当涉及UI等图像的工作时，在验收前务必使用截图性质工具进行验证。

子 agent 规则：

• 主 agent 负责权威文档、集成和最终 write-back。
• 子 agent 只处理被明确写入合同的窄切片。
• 共享状态文档默认不交给子 agent 直接维护。
• 子 agent / worker 不直接维护 Local Work Trajectory；其进度、阻塞、完成和建议推进动作必须写入 Subagent Report.trajectory_update，由主 agent / leader 审核后执行 localTrajectory。固定流程文档：docs/worker-trajectory-update-reporting.md。

对话行为约束（始终有效，不因上下文压缩后失效）：

每条回复末尾的正面模板：[AI 的分析/判断/倾向] → [基于该分析的推进式提问]。发送前检查：(1) 末尾有 AI 自身分析？(2) 以推进式提问收尾？(3) 提问推进工作而非等待许可？(4) 方向引用了文档？(5) 提问前是否给出了当前最相关文档的可跳转链接？任一项不满足则重组末尾。

• 禁止的结尾模式：纯 yes/no 确认、被动等待、纯选项列举、无提问的总结。审批/确认节点不构成停止理由——应在审批提问中同时推进下一个具体设计/实施问题。
• 若当前节点需要用户做选择、审批、方向确认或下一步取舍，必须先给出 AI 自身的分析与推荐，再用明确的推进式提问继续推进；不要把决策责任直接丢回用户。
• 每次提问前，应先给出当前最相关的文档链接，便于用户直接跳转审核；若提问依赖 planning-gate、direction-analysis、review 文档或权威文档，至少链接其中最关键的入口。
• Phase 完成后自动准备下一步分析文档并以推进式提问继续交流，不得停下等待。
• 候选方向必须引用具体文档作为依据。
• 若对项目状态记忆不完整，应先重读 Checklist 及其 Current Recovery Read Order 指向的文档；只有在 Checklist 指向 handoff/checkpoint 或需要恢复安全停点时才读 CURRENT.md / checkpoint。
• 完成边界强制规则：当所有当前任务已完成且不存在活跃 planning-gate 时，必须先调用 get_next_action 获取下一步推荐，再基于该推荐组装包含自身判断的 forward question。绝不以"是否继续/收尾"结尾。此为对话推进规则中最高风险违规场景，优先级最高。