docs: add agent citation and PR cross-reference rules

[Gandy2025]

Summary

• Add "Cite the tree when it matters" rule to During the Task section — agents mention tree nodes that influenced their decisions
• Add "Link tree PRs and code PRs" rule to After Every Task section — tree PR and code PR cross-reference each other in PR body

Motivation

Tree's value is invisible to users — agents read it and make better decisions, but users don't see the connection. These two rules make tree value passively visible:

1. Daily work: agents cite tree sources when decisions are influenced
2. PR review: reviewers see the decision-execution link between tree and code PRs

Scope of this PR

This PR only updates the bundled template (assets/framework/templates/agents.md.template). It affects:

• New tree repos initialized with first-tree init after this version — the new rules are written into AGENTS.md automatically
• Existing tree repos — NOT auto-refreshed. Per the current CLI design (upgrade.ts:282-289), framework block updates are surfaced as a manual task in progress.md after running first-tree upgrade, instructing maintainers to "compare the framework section in AGENTS.md with the bundled template and update the text between the markers."

Whether to switch to automatic framework block refresh is a separate design decision (see "Follow-up" below) and intentionally out of scope here.

Test plan

• Run first-tree init in a fresh repo, verify the generated AGENTS.md contains both new rules
• Run first-tree upgrade in an existing tree repo, verify progress.md includes the "Compare the framework section..." manual task pointing maintainers to sync the new rules

Follow-up (separate PR/issue)

Discuss whether first-tree upgrade should automatically refresh the AGENTS.md framework block (analogous to how SOURCE_INTEGRATION block is auto-replaced in source-integration.ts:214-228). Open questions:

• Replace the manual task in upgrade.ts:282-289?
• How to handle AGENTS.md vs CLAUDE.md when they're separate files (not symlinked)?
• How to handle user customizations inside the framework block, even though the marker forbids them?

🤖 Generated with Claude Code

[bingran-you]

GitHuber Update

Verdict: ACTION NEEDED — The new rules will not reach existing tree repos via first-tree upgrade.

The added bullets in assets/framework/templates/agents.md.template:36 and assets/framework/templates/agents.md.template:47 only affect newly created AGENTS.md files. renderTemplates() only creates missing files during init (src/engine/init.ts:140-151), and the tree upgrade path never rewrites the existing framework block in AGENTS.md; it either returns early as already up to date or refreshes version/skill metadata plus the source-repo index only (src/engine/upgrade.ts:530-567). As written, the PR body's rollout/test plan is incorrect: running first-tree upgrade on an existing tree repo will not add these rules.

Please either add a tree-side AGENTS.md framework refresh path (and an upgrade test for it) or narrow the change and test plan to newly initialized trees only.

---

Agent note: this reply was prepared and posted by githuber running locally for the active account.

[Gandy2025]

Thanks for the careful review — you're right that the original PR body's test plan was wrong, and I've updated it.

After tracing the code more thoroughly, I'd like to push back gently on the proposed remedy and propose a split:

The current "manual refresh" is intentional, not an oversight. upgrade.ts:282-289 deliberately emits a manual task into progress.md instructing the maintainer to compare and update the AGENTS.md framework block. rules/agent-instructions.ts:47-50 only checks for marker presence, not content match. Compare with the SOURCE_INTEGRATION block, which is auto-replaced by source-integration.ts:214-228 — so the project clearly distinguishes between "framework block" (human-reviewed) and "source-integration block" (CLI-managed).

Adding a refreshAgentsFrameworkBlock() would therefore be a design change, not a bug fix:

• It contradicts the manual task currently emitted in upgrade.ts:282-289 (would need to be removed)
• It needs to handle the AGENTS.md ↔ CLAUDE.md split (sometimes symlinked, sometimes separate files per rules/agent-instructions.ts:77-107)
• It needs a fallback for missing markers and user customizations inside the marked region

Proposed split:

1. This PR — narrow scope to template update only. Updated body reflects that:

   • New tree repos pick up the rules via first-tree init
   • Existing tree repos pick them up via the existing manual task in progress.md after first-tree upgrade

2. Separate PR/issue — discuss whether first-tree upgrade should switch from manual-task-emit to auto-refresh for the framework block. If yes, a focused PR can replace the manual task, handle the AGENTS.md/CLAUDE.md cases, and add tests — without being coupled to a content change.

This keeps the content change reviewable in isolation and lets the architectural question be discussed on its own merits. Happy to open the follow-up issue right after this lands. If you'd prefer to fold the auto-refresh into this PR instead, I'll do that — just want to flag the design implications first.

[bingran-you]

The revised PR body still doesn’t match the current upgrade behavior.

first-tree upgrade reads the bundled skill version from skills/first-tree/VERSION (src/engine/upgrade.ts:354) and treats tree metadata as current when compareSkillVersions(localVersion, packagedVersion) === 0 (src/engine/upgrade.ts:530-546). The existing dedicated-tree test locks that behavior in: a current 0.2.0 tree returns without writing .first-tree/progress.md (tests/upgrade.test.ts:253-281).

So an existing tree that is already on 0.2.x will not receive the manual "Compare the framework section..." task that the revised scope/test plan now depends on. As written, this change is still only guaranteed to reach newly initialized trees.

Please either narrow the scope/test plan further to first-tree init only, or change the tree-upgrade path so existing trees actually receive the manual or automatic framework refresh signal.

Separately, this PR also edits a shipped runtime template without the required assets/framework/VERSION bump from the package contract (first-tree-skill-cli/build-and-distribution.md).

Agent note: this reply was prepared and posted by githuber running locally for the active account.

[bingran-you]

@Gandy2025 感谢 pushback — 把 upgrade 的行为读得更仔细后，其实结论比我之前说的更简单。总结一下这个 PR 要合并需要改的三件事：

需要修改的内容

1. 重新指向新路径（#113 合并后产生的结构性冲突）

#113（refactor(cli): introduce tree/breeze product namespace）把 assets/framework/ 移到了 assets/tree/。你的 PR 还在改 assets/framework/templates/agents.md.template，这个路径现在在 main 上已经不存在。需要 rebase 到 main，然后把改动挪到：

assets/tree/templates/agents.md.template

2. Bump assets/tree/VERSION

这一条是 unblock 你原先设计顾虑的关键：你担心的"现有 tree repo 收不到刷新信号"其实已经被现有机制解决了，触发条件就是 VERSION bump。

src/products/tree/engine/upgrade.ts:530-546 的逻辑：

• 当 compareSkillVersions(localVersion, packagedVersion) === 0 时，upgrade 直接 return 0，不写 progress.md
• 只要 assets/tree/VERSION 有 bump（比如 0.2.6 → 0.2.7），现有 tree repo 运行 first-tree upgrade 就会触发 drift 分支，走到 upgrade.ts:282-289 把 "Compare the framework section..." 写进 .first-tree/progress.md

所以你提出的 scope split 是对的——这个 PR 不需要改 upgrade 代码，但 必须 bump VERSION 才能让现有 tree 实际收到信号。这也是 first-tree-skill-cli/build-and-distribution.md 包合约的要求。

3. 更新 PR body 和 test plan

改完上面两项后，test plan 建议改成：

- [ ] Run `first-tree init` in a fresh repo → 新生成的 AGENTS.md 包含两条新规则
- [ ] 在一个跑过 `first-tree init` 的测试 tree repo 里把 `.first-tree/VERSION` 手动降到 0.2.6，然后运行 `first-tree upgrade` → `.first-tree/progress.md` 包含 "Compare the framework section..." 任务

合并后 follow-up（不在此 PR 范围）

你提到的 auto-refresh vs manual-task 的设计讨论确实值得单独 issue，这个保持现状即可。

---

简单说：rebase 到新路径 + bump assets/tree/VERSION + 更新 test plan 三件事做完就可以合并。参考 #115 的 rebase 模式（#113 的重构让所有 open PR 都需要类似处理）。

[bingran-you]

Breeze pickup test (2026-04-20T22:56:53Z): @bingran-you could you review this?

[bingran-you]

Re-checked this against current main.

There are still no new commits beyond d713b40, and the PR is still conflicting with main, so the April 16 blockers still apply:

• rebase onto current main and move the template change to assets/tree/templates/agents.md.template
• bump assets/tree/VERSION so existing tree repos get the framework-refresh task on upgrade
• update the PR body and test plan to match that rollout

I'm leaving the existing changes-requested review in place. Once those updates are pushed, I can re-review.

This reply was drafted by breeze, an autonomous agent running on behalf of the account owner.