std-agent: Instructions file for Codex

std-agent

stdagent 是纯 Go CLI，以 .stdai/ 为单一真相源，将 rules、skills、commands、references 和 subagents 转换为 25 个 AI CLI target 的原生配置。本仓库是其源码并用自身规则自举。

结构

• cmd/stdagent/：程序入口。
• internal/cli/、config/、parser/、source/：命令、配置与源文档读取。
• internal/transformer/：协议层和 target adapter。
• internal/runner/、writer/、state/、budget/：同步、原子写入、状态和上下文预算。
• docs/：格式、架构及各 target 的官方证据。

技术栈：Go 1.26、Cobra、BurntSushi/toml、goccy/go-yaml、doublestar、GoReleaser；工具链由 mise 管理。

关键约束

• .stdai/standards/ 是 AI 配置源。生成的 CLAUDE.md、AGENTS.md 和 target 目录只通过 go run ./cmd/stdagent sync 更新。
• frontmatter、协议或 target 映射属于跨 25 个 target 的兼容性变更，必须对照 docs/format-spec.md、docs/conversion-rules.md 和对应 docs/targets/ 证据。
• 多 target 共享同一路径时，内容必须字节一致；AGENTS.md 是 target-neutral 的共享 rules 层，target 专属能力写入各自 sidecar。

Done means

相关回归测试已覆盖，且以下命令通过：

mise run check
go run ./cmd/stdagent sync --no-pull --strict
go run ./cmd/stdagent status

commit-style

Conventional Commits 和安全暂存要求

用户要求 commit 时：

• 格式为 Conventional Commits 1.0.0：<type>(scope): <description>；scope 与现有模块和提交历史一致。
• breaking change 使用 ! 和 BREAKING CHANGE:。
• 只显式暂存当前任务文件；密钥或 .env 类文件先报告，不擅自提交。
• 不添加 Co-Authored-By 或 AI 署名。

no-history-rewrite

保护已推送分支和 release tag

• 已推送分支只追加 commit 并 fast-forward push；main 和受保护分支永不 force-push。
• amend 或 rebase 仅限本人独占、尚未共享的 WIP 分支。
• 已推送并触发发布的 tag 不删除；修复使用更高 patch 版本。

test-requirements

核心转换与写入变更必须有针对性回归测试

修改 transformer、runner、writer 或 parser 时，测试必须先复现风险，再证明修复：

• target 或 transformer 变更覆盖 5 种 type 的关键 fanout 和共享路径。
• runner 控制流覆盖相关 flag、首次与重复 sync、prune 和边界保护。
• writer 变更覆盖 unchanged、overwrite 和 atomic 路径。

Done means go test ./...、go test -race ./internal/runner/... 和 mise run check 通过；无法执行的验证标记 UNKNOWN。