Intent

Imported from zzyu5/Intent (AGENTS.md). Install upstream with npx skills add zzyu5/Intent. Copyright stays with the author.

IntentDSL 协作原则

目标与责任

• 推进可运行的 lowering 骨架与真实算子性能；问答、调查、清理按用户指定范围完成，不用测试、报告或管理流程冒充进展。
• Intent 是可编程算子 DSL，不默认采用“高层算子图交给 compiler 决定全部算法”的模型。作者负责算法与显式程序组织，包括多个 kernels 和 host 编排；compiler 在既有语义下形成物理程序并优化。
• 合法的类型、shape、数值与 effect 表达 lowering 失败，是 compiler 问题；不要求作者换算法或反复拆 kernel 迁就实现缺陷。
• 明确语义与适用条件下，允许 lowering 到高性能 micro-kernel/目标构造，不必由通用 IR 重建全部底层细节；也不能让 leaf 猜测缺失语义或接管整个算子。

规格与参考

• doc/ 是最终设计规格。动 DSL、KIR、compiler IR/pass、provider 或 runtime 前，从 doc/index.md 进入并完整阅读相关章节；实现向规格收敛，不为保住现状反改规格。
• 只有用户确认设计变化才改规格；进度、实验失败、临时字段和性能数字不写入 doc/。Memory、短期记录和 report 只能帮助定位，不能替代当前原文。
• 架构、pass 与性能决策先对照外部 ../ref/triton、../ref/tilelang 或相应成熟目标实现：先比较 surface 的语义合同，再确认同类职责由哪层承担；关键结论给出双方 file:line、具体差异与后果。参考边界与机制，不照搬 surface，不凭框架名称作判断。
• 不把已有文档中的更强保证自动当作必要目标。默认保序、严格逐操作舍入、额外 dtype 限制等若强于成熟参考，先说明作者需求、适用范围与实现成本；发现合同本身不合理时先提出语义修正，不持续堆 lowering 迁就它。普通 reduce、prefix scan 与 ordered loop 各按自己的合同处理。
• 合同相同且 provider 已有原生 primitive 时优先直接映射。Triton/TileLang 已承担的归约树、线程通信、布局和 pipeline 不在 Intent 重建；不为同一个原生能力另造 form、plan 或运行时分支。只有实际缺失的执行事实或不匹配的目标能力才引入必要扩展。
• dtype 分清外部存储/ABI、source 运算、accumulator/result 与后端内部计算。先核对参考的 promotion、literal 推导和 store conversion；typed IR 要求类型闭合，不等于作者必须处处同 dtype 或显式 cast。额外限制须有独立理由，也不能以复用后端为由改变已声明的累加精度、NaN/tie 或 ABI。
• examples/kernels/ 只保存作者算法；experiments/{gpu,cpu,mlu,agent_tritonbench}/ 分别保存对应实验的执行入口、操作说明、baseline 与结果。main 的 GPU 产品与实验只推进 Triton/cuTile；TileLang 后端、corpus 与结果保存在 archive/tilelang-backend 分支，不在 main 恢复或推进。外部 ../ref/tilelang 仍可用于成熟编译器职责与机制对照。
• experiments/ 保留论文所需的历史入口、baseline 与结果，产品推进不再修改或回写这些材料。既定 30 个完整 program 是产品使用、编译、运行与优化观察的主入口；复用 examples 中唯一算法和 host 编排，不复制算法或重建论文实验 registry。
• 中间 MLIR、生成的后端源码和编译缓存放在仓库外（如 ~/.cache/intentdsl/）；实验目录只保留执行入口、必要的 baseline 和结果。

IR、pass 与目录

• 分块、布局、ownership、遍历、复用、materialization 等执行决定必须存在于相应 IR 与 passes；shared 和 target-local 各守职责，serializer 只拼写已决定的结构。
• Policy 根据 current typed semantics、def-use、coordinate relations、effects、lifetime 与目标能力决策，不靠算子名、字符串标签或单条样本。正式 typed 参数、shape 与 capability 可以参与合法性判断。
• 复用已有 carrier；只有真正缺少执行事实才增加 IR 表达。目标 API 的拼写差异不自动要求修改 shared IR。
• 只保留一条有效执行路径。迁移后删除旧路径，不保留兼容开关、默认值或异常回退掩盖未实现。
• 目录表达稳定职责与 lowering 边界；同层同抽象，强耦合文件相邻，source 与 runtime 相邻。不随手造层级、平铺模块或放入缓存和环境。
• 可查清的信息自行调查；只有现有规格无法决定的语言语义、作者可观察行为或核心架构分叉才暂停问用户，不能用另造产物填补不确定性。

产品运行与论文实验

• 产品工作围绕既定 30 个 program 的完整编译与真实执行，包括显式多 kernel 调用；后端实现缺失属于待修复项，必要时修改 Weft 主线，不把未实现伪装成硬件限制。
• 产品性能先观察自身版本、同类工作量与实际生成结构，既有论文 reference 与成熟实现用于校准和分析，不要求每个 program 有固定外部性能对手。正确性仍按算法合同核对，不通过放宽容差掩盖错误。
• 复用产品 program 和现有 compiler/runtime 完成必要验证，不另造算法副本、论文实验矩阵或独立的边界、压力、兼容测试。生成源码、IR、缓存及运行观察留在仓库外。
• 编译、native materialization、首次调优与热调用分别记录。准备和编译可按资源预算并发，同机性能计时避免干扰；完整程序的 host 准备、数据转移和同步按实际计时范围说明。
• 论文固定版本测评与产品修改分开；未经明确要求不更新论文 CSV、baseline 或首次 agent 交付成绩。
• 同算法、相同输入规模与外部 dtype 下比较；ABI、辅助输出、布局转换与精度细节注明，不一概阻断计时。Compiler 仍必须保持 Intent 语义。
• 报真实完整算子时间、reference 时间及清楚的比值；编译/JIT/tuning 不是算子耗时，CSV 不承担历史审计。差距先查物理结构，再查 provider/外部 compiler/measurement，不无证据归因给下层。
• Agent 实验每题每语言组只交付一次完整程序，提交后不反馈错误或性能继续生成。Bench 自带 reference 保留；开发端修 compiler 不改写首次交付成绩。
• 手册 MCP 只提供通用语法、类型、接口与语义规则及必要的最小语法片段，不提供完整算法示例、评测题解法、reference 代码或针对性的算法与调优建议。

禁止与交付

• 禁止任何 hash / SHA / checksum 校验来源或产物。
• 不增加版本号、CHANGELOG、迁移指南、deprecation 标记；用 Git 记录修改。
• 不做未经要求的重构、目录整理、注释批量补写或 README 更新。
• 不吞异常、不加默认值兜底或“防御性”假支持；未实现明确报 unsupported / NotImplementedError。
• 仅在用户明确要求时创建或更新 report；读取报告不等于授权续写。长任务用 todoskill 保存必要节点，内部记录不另作交付。
• 只改必要文件，除用户指定或 todoskill 的单份短期记录外，不新建计划/进度文档。完成一个连贯改动后提交自己的文件，保留他人修改，不自动 push。
• 简明报告实际结果、关键取舍和未完成项；未经运行不宣称数值正确或性能达标。