AGENTS.md should be thin handbook + trigger-based pointers

[Drswith]

Context

We reviewed the current AGENTS.md and found it mixes multiple document types (README-style product intro, architecture dump, process gates, and project memory policy). This reduces signal for agents and increases drift risk (inline directory trees, copied types, duplicated command catalogs).

Decision

AGENTS.md will be maintained as a thin but self-contained execution handbook plus a trigger-based pointers index:

• Inline (must be self-contained):

  • Mission / non-goals (very short)
  • Agent Quickstart (5–8 lines: classify → decide OpenSpec → implement → validate → report)
  • Must / Must Not (hard constraints)
  • Validation triggers and commands (lint/typecheck/test/openspec/release artifacts as applicable)
  • Work Intake decision tree (explicit if/else)
  • Delivery Closure mapping (what “done” means and what to do next)
  • File-scoped red lines (e.g. generated outputs, archives)

• Pointers (“when X, consult Y”) to route detailed/volatile knowledge:

  • Source-of-truth type definitions (point to real TS files, no copied snippets)
  • Full command catalog / schema (point to quantex commands / quantex schema or docs)
  • Large architecture maps and directory trees (move to docs/ if needed)
  • Release runbooks/ADRs, OpenSpec specs, recovery procedures

Rationale

• AGENTS.md is injected into every agent session; hard constraints must be unmissable.
• Pure “directory-of-links” formats rely on agents always expanding links; behavior varies across tools.
• Inline copying of trees/types drifts quickly; pointers reduce rot while keeping critical rules present.

Non-goals

• Turning Quantex into a workflow orchestration platform.
• Duplicating the user-facing README or full CLI command tables inside AGENTS.md.

Follow-ups

• Propose an OpenSpec change to rewrite AGENTS.md to the above structure.
• Move or delete drift-prone inline sections (src tree, copied types, full CLI command table) and replace them with trigger-based pointers.

[Drswith]

已按仓库流程完成收口，结果如下：

• 已提升为 issue：[Docs/Workflow]: Trim AGENTS.md into a thin execution handbook #70
• 实现 PR 已合并：docs: trim AGENTS handbook
• OpenSpec archive follow-up 已合并：docs: archive trim-agents-handbook change
• 归档后机械去重已合并：docs: dedupe AGENTS handbook project-memory requirements

当前状态：

• AGENTS.md 已重写为 thin execution handbook + trigger-based pointers
• discussion 结论已提升为 repo-native artifacts：session summary、ADR 0005、OpenSpec archived change
• project-memory 主 spec 已同步最终 requirement，并完成归档闭环
• issue [Docs/Workflow]: Trim AGENTS.md into a thin execution handbook #70 已关闭，当前无 active OpenSpec changes

这条 discussion 作为探索入口已经完成使命，后续以 ADR / archived OpenSpec / merged PRs 为准。